Local development

arg serve runs an app from a directory on your machine, injects the SDK modules, and roots fs in that directory. The same import { fs } from "@arg-ai/sdk" your app ships with reads local files while you develop; nothing is uploaded.

~/work/my-app — arg

arg serve . --open                 # your CLI login + local files
arg serve . --write --open         # also let the app change local files
arg serve . --anonymous --open     # disk only, no account access
arg serve . --workspace research   # bind chats and Actions to another cloud workspace

Flag	Default	Effect
`--port`	`3333`, `0` picks a free port	Loopback port
`--open`	off	Open the app in a browser
`--write`	off	Allow the app to change files inside the served directory
`--anonymous`	off	Serve disk files only; no account credentials and no cloud requests
`--workspace`, `-w`	the CLI’s active workspace	Cloud workspace id or name for chats, Actions and the resource namespaces

Install the CLI and sign in first: see the command line guide. Login and workspace access are checked before the server starts. The CLI serves HTML and built assets; build a TSX or JSX app with its own tool and serve the output, since arg serve is not a React compiler.

What the app sees

fs reads and writes local disk, rooted in the served directory. Relative paths resolve beside the HTML file and / is the directory. Hidden paths, symlinks and non-regular files are excluded; content is capped at 8 MiB, listings at 1,000 entries, and at most 16 requests run at once. copy needs an unused destination, move may replace one, and remove refuses a non-empty directory. createOnly is atomic; baseRevision is unsupported because outside editors do not take part in the server’s write protocol. Stable ids and db are unavailable.
With the CLI’s login (the default), await arg.ready discovers the selected cloud workspace, and auth, users, permissions, actions, agents, chat, workspace, comments, notifications, integrations, automations, code, sites and servers go through a bridge the CLI owns. Those refer to the cloud workspace: a permission or comment is on a cloud file, never on the local copy.
ui and host need an Arg application host and report unsupported_capability.

--write controls disk writes only. It does not gate cloud Actions or mutations; those follow your account’s permissions.

Connecting from a script

A Node script can talk to a running arg serve too. The launch URL the CLI prints carries a one-run token in its fragment; pass it explicitly outside a browser:

import { createLocalClient } from "@arg/sdk/local";

const arg = createLocalClient({
  baseUrl: "http://127.0.0.1:3333",
  token: process.env.ARG_LOCAL_TOKEN!,
});
try {
  console.log(await arg.fs.read("./notes.txt"));
} finally {
  arg.dispose();
}

baseUrl must be the exact loopback origin the CLI printed. In a browser the client uses the page’s own origin and the session the launch URL established.

What stays on your machine

Serve only code you trust with your account. In account mode the app can perform the supported backend reads and mutations as you, under your existing permissions - this is an explicit developer session, not a visitor-consent mechanism. The design keeps the credential out of the page:

Access tokens and API keys never leave the CLI. The browser holds a per-run loopback session; each server start mints a new one, and the fragment is removed from the URL before the app loads.
Requests need that session plus exact host and origin checks. The bridge accepts only reviewed method and path contracts, pins the workspace and organization, checks Site ownership, strips incoming headers, refuses redirects and sanitises upstream errors. It cannot manage credentials or proxy arbitrary URLs.
Service-worker registration is refused so nothing persists across sessions; ordinary web workers work.
Signing out, or another CLI process rotating the login, stops future requests; restart the server afterwards. Stopping the server revokes its session. Requests Arg has already accepted may finish.

--anonymous skips all of this: no account, no cloud calls, disk files only.

Getting started

Building with agents

Core concepts

Apps

Arg SDK

Integrations

Command line

Recipes & patterns

Changelog

Local development

What the app sees

Connecting from a script

What stays on your machine

​What the app sees

​Connecting from a script

​What stays on your machine

What the app sees

Connecting from a script

What stays on your machine