> ## Documentation Index
> Fetch the complete documentation index at: https://developers.arg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Local development

> Run an app from a folder on your machine with arg serve: the same @arg-ai/sdk imports read local disk, while chats, Actions and the other namespaces use your CLI login.

`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.

```bash title="~/work/my-app — arg" theme={null}
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](/guides/cli). 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:

```ts theme={null}
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.