Arg SDK overview

The same fs, chat, actions and resource namespaces run inside an app opened in Arg, in a published Site, on your own server or in CI, against a folder on your machine, and inside the scripts an agent writes during a run. Custom apps import the host-provided @arg-ai/sdk, matching Arg’s established npm scope. Agent scripts and installed server or hosted clients use @arg/sdk. What changes between those places is the transport that carries a call and the permissions the host grants, never the resource API you write against.

import { actions, auth, chat, fs } from "@arg-ai/sdk";

const me = await auth.principal();
const settings = await fs.readJSON<{ title: string }>("./settings.json");
const turn = await chat.start(`Review ${settings.title}`, { openPanel: true });
const catalog = await actions.list({ query: "summarize" });

Where it runs

Where your code runs	How to get a client	Credentials	Guide
An `.html`, `.tsx` or `.jsx` app opened in Arg	`import { fs } from "@arg-ai/sdk"` - nothing to install	None in your code; the viewer’s grants in Permissions	Apps inside Arg
A published Site opened from Apps in Arg	Bundle `@arg/sdk` into the Site	The signed-in viewer, after they allow Workspace access	Published Sites
A Site or hosted frontend outside Arg	`createHostedClient` over your own gateway	A session your app server already owns	Published Sites
A server, a job, CI	`createServerClient` from `@arg/sdk/server`	An API key or bearer token	Servers and CI
A folder on your machine, during development	`arg serve ./my-app`	The CLI’s own login, or `--anonymous`	Local development
A script the agent runs with `run_code` or `run_bash`	`import { fs } from "@arg/sdk"` - preinstalled	A short-lived capability the run injects	Agent scripts

Every namespace below is a named export from the SDK entry for its runtime and a property of the default arg object. Imported namespaces are lazy: they follow whichever host the code is running in. An explicit client from one of the factories is bound to its transport until you call dispose().

Namespace	What it covers
`fs`, `permissions`, `db`, `host`	Workspace files: read, write, share, watch, embedded SQLite, open in Arg
`chat`, `workspace`	Chats: start and continue conversations, list accessible workspaces
`actions`, `agents`	Actions and agents: the typed capability catalog and agent runs
`comments`, `notifications`, `integrations`, `automations`, `code`, `sites`, `servers`	Workspace resources
`auth`, `users`, `ui`	Who is calling, who is in the workspace, and the app chrome an app can register

The full method list, every error code and the wire operations are in the reference.

Install

Nothing to install inside Arg: the hosts that run your app resolve @arg-ai/sdk themselves. The earlier @arg/sdk custom-app spelling remains an alias for saved apps. Everywhere else the unified client is a normal package.

npm install @arg/sdk

It is pure ESM, has one dependency (the TypeScript client it builds on for the server surface, published as @arg-ai/sdk) and needs Node 18 or later for the built-in fetch. Subpath imports such as @arg/sdk/fs and @arg/sdk/chat expose the same objects as the root; the runtime factories keep their own entry points: @arg/sdk/server, @arg/sdk/local, @arg/sdk/hosted and @arg/sdk/gateway.

Permissions travel with the host, not the import

Importing the SDK grants nothing. Each host decides what a call may do:

Inside Arg, the viewer’s Permissions menu on the preview: Workspace access (read or read and write, over the file’s folder or the whole workspace) and Actions are separate switches. A denied call fails with permission_denied or disabled; the SDK never falls back to another credential.
On a server, the API key’s own permissions. The backend checks every call; basePath is a convenience for relative paths, not an authorization boundary.
In an agent script, the turn’s read-only state, its Actions gate and its approval mode.

The same code therefore behaves differently in different places by design. A namespace a host cannot serve rejects with unsupported_capability rather than pretending; check the availability table when a call surprises you.

How it relates to the other SDKs

@arg-ai/sdk is also the established server client with the Run lifecycle and resilient uploads. Custom apps receive their host-scoped modules under that same package spelling without downloading or receiving server credentials.
window.arg is the injected global that HTML apps have always used. It still works. The host-provided @arg-ai/sdk gives custom apps the same objects as typed imports.
@arg/actions and @arg/ui stay the React preview facades. actions from the app SDK is the same catalog; ui is the same app chrome contract without the React components.

Apps inside Arg

Read and write workspace files, react to changes, and open chats from an HTML or React app.

Servers and CI

Drive a workspace from a job with an API key, including conditional writes and Site builds.

Chats and desktop harnesses

Start a conversation with the cloud agent, or with Claude Code or Codex on the desktop.

Reference

Every method, every error code, and which host serves which namespace.

Getting started

Building with agents

Core concepts

Apps

Arg SDK

Integrations

Command line

Recipes & patterns

Changelog

Arg SDK overview

Where it runs

Install

Permissions travel with the host, not the import

How it relates to the other SDKs

Apps inside Arg

Servers and CI

Chats and desktop harnesses

Reference

​Where it runs

​Install

​Permissions travel with the host, not the import

​How it relates to the other SDKs

Apps inside Arg

Servers and CI

Chats and desktop harnesses

Reference

Where it runs

Install

Permissions travel with the host, not the import

How it relates to the other SDKs