> ## 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. # SDK reference > Every Arg SDK namespace and method, which hosts serve them, the client factories, and the error codes a call can reject with. Every namespace is a named export from the SDK entry for its runtime and a property of the default `arg` object. Custom apps use the host-provided `@arg-ai/sdk`; agent scripts and installed factory clients use `@arg/sdk`. `arg.ready` is a promise; await it before reading `arg.context`. Imported namespaces are lazy and follow the current host. A client from one of the [factories](#client-factories) is bound to its transport until `dispose()`. ## Namespaces and methods | Namespace | Methods | Result and notes | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `auth` | `principal()` | `{ kind: "user" \| "service_account", id, name, email }` | | `users` | `list()` | `{ id, kind, name, role }[]` for the bound workspace | | `workspace` | `list()` | `{ id, name, organization_id }[]` the identity can reach in the workspace's organization; no create, update or delete | | `fs` | `read(path, options?)`, `readJSON(path, options?)`, `readBytes(path, options?)`, `readFile(path, options?)` and their `ById` forms | Text, parsed JSON, bytes, or `{ content, encoding, mimeType, size, revision, ... }`; `fresh: true` bypasses read caches | | `fs` | `dataUrl(path)`, `assetUrl(path)` and `ById` forms | An inline data URL, or `{ url, expiresAt, size, contentType }`; an asset URL is not a share link | | `fs` | `info(path)`, `infoById(id)`, `exists(path)`, `resolveId(id)`, `getId(path)` | Metadata, existence and id resolution; ids are cloud-only | | `fs` | `list(path?)`, `glob(pattern, { cwd? })`, `search(query, { path?, include? })` | Entries, matching paths, or `{ path, line, text }` hits, bounded by the transport | | `fs` | `write(path, content, { encoding?, baseRevision?, createOnly? })`, `writeJSON(path, value, condition?)` | `{ path, revision }`; conditions are honoured over HTTP and refused, never ignored, elsewhere | | `fs` | `mkdir(path)`, `move(from, to)`, `copy(from, to)`, `remove(path)` / `delete(path)` | Need write authority; targets are literal file paths | | `fs` | `watch(path, callback, { emitInitial?, intervalMs? })`, `watchById(id, ...)` | Returns a synchronous stop function; polling transports go no faster than 250 ms | | `host` / `fs` | `open(path)`, `openById(id)` | Opens the file in Arg; needs an application host | | `db` | `query(path, sql, params?)`, `exec(path, sql, params?)`, `tables(path)`, `schema(path, table)` | File-backed SQLite inside an Arg preview only | | `actions` | `list(options?)`, `schema(id)`, `describe(id, options?)` | Discover ids and input contracts before running | | `actions` | `run(id, input, { idempotencyKey? })`, `runBatch(calls)`, `getRun(id)`, `listRuns(options?)` | `{ runId, status, output?, error? }`; check `status`, never retry an accepted write blindly | | `actions` | `ready`, `enabled`, `readOnly` | What the host granted | | `agents` | `run(message, options?)` | The `agent_run` Action; both the Action's and the agent's status must be terminal | | `chat` | `create({ title?, agent? })`, `send(id, message, { model?, openPanel? })`, `start(message, options)`, `continue(id, message, options)` | An accepted or queued turn with `panelOpened`; `agent` is `arg`, `claude_code` or `codex` | | `chat` | `list({ limit?, offset? })`, `search(query, { limit? })`, `get(id)`, `status(id, callId)`, `open(id)` | Workspace-bound chats for this identity; nothing is streamed | | `comments` | `list(path, { includeResolved? })`, `create({ path, body, parentId?, metadata? })`, `update(id, body)`, `resolve(id, resolved?)`, `remove(id)` | Cloud file paths, even under `arg serve` | | `permissions` | `share({ path, kind, userId, permission })`, `shareFile(path, options)`, `shareFolder(path, options)` | Permission is `read`, `write` or `manage`; caller needs `manage`, and recipient must be in the workspace organization | | `notifications` | `list({ limit?, offset?, unreadOnly? })`, `send(input)`, `sendToMe(input)`, `sendToUser(userId, input)`, `markRead(id)`, `markAllRead()` | A title or target is required; recipient preferences and channel selection still apply | | `integrations` | `providers()`, `connections({ organizationId?, providerId? })`, `triggers(providerId)`, `proxy(alias, path, { method?, body? })` | Discovery never returns credentials; `proxy` needs a server integration capability | | `automations` | `run({ filePath, document?, input? })`, `getRun(id)`, `stop(id)`, `history({ limit?, offset?, filePath? })`, `deployments()`, `pause(filePath)`, `resume(filePath)` | Automation files and their runs | | `code` | `run(command, { sandboxId? })` | `{ status: "completed" \| "failed", stdout, stderr, duration_ms }` | | `sites` | `list()`, `create({ slug, sourcePath, framework, access, displayName? })`, `get(id)`, `build(id, { autoPromote? })`, `version(id, versionId)`, `promote(id, versionId)`, `remove(id)` | Framework `static`, `vite`, `astro`, `next`, `worker`; access `public` or `workspace` | | `servers` | `list()`, `start({ command, port, name?, access?, actions? })`, `get(id)`, `stop(id)` | Long-running server lifecycle | | `ui` | `register(registration, handlers?)`, `available`, `readOnly`, `ready` | Returns `{ update, dispose }`; app chrome inside an Arg preview only | Every method accepts an optional final `{ signal, timeoutMs }` argument through the explicit clients; the lazy imports take it as their last parameter where shown. ## Availability by host | Namespace | App in Arg | Published Site in Arg | `arg serve` (account) | `arg serve --anonymous` | Server / CI | Capability token | Hosted gateway | Agent script | | --------------------------------------- | ----------------------------- | --------------------- | ---------------------------- | ----------------------- | ----------- | ------------------------- | ------------------ | --------------------- | | `fs` read | Yes, in scope | Yes, in scope | Local disk | Local disk | Yes | - | Per gateway policy | Yes | | `fs` write / conditions | Read and write; no conditions | Read and write | `--write`, no `baseRevision` | `--write` | Yes | - | Per policy | Writable turn | | `fs.open`, `host`, `ui` | Yes | - | - | - | - | - | - | - | | `db` | Yes | Yes | - | - | - | - | - | - | | `auth`, `users` | Yes | Yes | Yes | - | Yes | Principal only | Per policy | Yes | | `actions`, `agents` | Actions switch | Actions switch | Yes | - | Yes | Yes | Per policy | Turn gates | | `chat`, `workspace` | Workspace scope + Actions | Same | Yes | - | Yes | - | Per policy | Full access for sends | | `chat` with `claude_code` / `codex` | Desktop app only | - | - | - | - | - | - | - | | `permissions`, `comments` ... `servers` | - | - | Yes | - | Yes | `integrations.proxy` only | Per policy | Turn gates | A dash means the call rejects with `unsupported_capability`; the SDK never falls back to another credential to satisfy it. ## Client factories | Import | Creates | Runs in | | ---------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------- | | `import { arg, fs, ... } from "@arg-ai/sdk"` | The lazy client that follows the current custom-app host | Arg app hosts | | `import { arg, fs, ... } from "@arg/sdk"` | The lazy client bound to an agent run | Agent runtimes | | `createServerClient(options)` from `@arg/sdk/server` | An API key or bearer client bound to one workspace, with the legacy resources attached | Servers, CI | | `createCapabilityClient(options)` from `@arg/sdk/server` | A Site or Server Action-token client | App servers | | `createLocalClient(options)` from `@arg/sdk/local` | A client for a running `arg serve` | Browser or Node | | `createHostedClient(options)` from `@arg/sdk/hosted` | A browser client over a same-origin gateway | Browser | | `createGateway(options)` from `@arg/sdk/gateway` | The `(Request) => Promise` handler that serves hosted clients | App servers | | `createClient({ transport, callOptions })` from `@arg/sdk` | The same resources over a transport you implement | Anywhere | A custom `Transport` implements `context`, `call(operation, args, options)` and `dispose()`. The wire operations it must answer are the `SDK_OPERATIONS` export (`isSdkOperation` narrows a string); an unknown operation must reject, and a transport's policy must validate resource arguments, not only operation names. ## Error codes Every rejection is an `SdkError` with a `code`, a `message`, and when it came from a request, `status` and `requestId`. Key on the code, never the message. | Code | Meaning | | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `permission_denied` | Outside the granted scope, the bound workspace, or the turn's authority; a local harness from a non-desktop host | | `read_only` | The grant or the turn is read-only and the call would change something | | `disabled` | The call needs the **Actions** switch and it is off | | `unsupported_capability` | This host does not serve the namespace or option (embedded-only surfaces, conditional writes on a bridge, a desktop harness elsewhere) | | `bridge_unavailable` | No Arg host is present and no client transport was configured | | `invalid_argument`, `invalid_path`, `invalid_request`, `invalid_operation` | The call itself was malformed | | `invalid_base_url`, `invalid_endpoint`, `missing_credentials`, `missing_workspace` | A factory was configured incorrectly | | `server_only`, `browser_required` | The factory was used on the wrong side of the browser boundary | | `client_closed` | The client was disposed | | `aborted`, `timeout` | The call's signal fired, or its deadline passed | | `limit_exceeded` | A response or listing exceeded the transport's bound | | `rate_limited` | Too many calls under one capability | | `invalid_response` | The host or the API returned something the SDK could not parse | | `not_found` | The resource does not exist, or a run is not durable enough to look up | | `http_` | A request failed with a status the API gave no code for | Codes the API returns for its own reasons, such as `credits_exhausted`, pass through unchanged.