Servers and CI

createServerClient from @arg/sdk/server binds the whole SDK to one workspace with a credential you hold. It refuses to run in a browser: credentials stay on your side, and the backend checks every call against the principal’s own permissions.

import { createServerClient } from "@arg/sdk/server";

const arg = createServerClient({
  workspaceId: process.env.ARG_WORKSPACE_ID!,
  auth: { kind: "api-key", key: process.env.ARG_API_KEY! },
});
try {
  const state = await arg.fs.readFile("/state.json");
  await arg.fs.writeJSON(
    "/state.json",
    { ...JSON.parse(state.content), ran: Date.now() },
    {
      baseRevision: state.revision!,
    },
  );
  const sites = await arg.sites.list();
} finally {
  arg.dispose();
}

Options

Option	Meaning
`workspaceId`	The workspace every call is bound to
`auth`	`{ kind: "api-key", key }` for a user-owned or service-account key, or `{ kind: "access-token", token }` for a bearer token
`baseUrl`	Defaults to `https://api.arg.ai`; must be HTTPS except on loopback
`basePath`	The folder relative `fs` paths resolve against. A convenience, not an authorization boundary
`fetch`	A custom `fetch`, for tests or an instrumented client
`timeoutMs`	Per-call deadline; each call also accepts `{ signal, timeoutMs }` as its last argument

A user-owned key acts as that user; a service-account key acts as the account, and user-only endpoints refuse it. The SDK never widens what the key can do.

What the client serves

Everything in the reference except the embedded-only surfaces: fs with conditional writes, actions and agents, chat and workspace, auth.principal(), users, permissions, and the resource namespaces (comments, notifications, integrations, automations, code, sites, servers). db, host, ui and fs.open need an Arg application host and report unsupported_capability here; chat.start with a desktop harness is refused too, since those run inside the desktop app.

Requests, deadlines, cancellation

Every request carries a deadline, refuses redirects, sends no cookies and reads at most 32 MiB. Mutating requests are never retried automatically. Cancelling a call through its signal stops waiting; it cannot undo a mutation the server already accepted, so reconcile with a read before retrying. dispose() aborts every in-flight call and stops every fs.watch the client created; a call after that rejects with client_closed.

The legacy client underneath

The server client is built on @arg-ai/sdk and exposes it, so a script written against that package keeps its resources and gains the new namespaces:

const run = await arg.run("Chart revenue by region from data.csv"); // the Run lifecycle
const result = await run.result();
await arg.files.upload({ data: bigBlob, name: "video.mp4" }, { onProgress });
const ws = await arg.workspaces.create({ name: "quickstart" });
const keys = await arg.keys.list();

files, workspaces, chats, keys and agentLifecycle are those legacy resources unchanged: their DTOs, errors and retry behaviour are the legacy contracts, documented on the TypeScript SDK page.

Advanced file transfers

arg.fs reads and writes whole files as JSON. For anything large or streamed - multipart uploads with per-part retries, streamed downloads, batch operations - use arg.files, the legacy files resource, which switches to a resilient multipart upload above 16 MiB.

Sites and Servers with their own tokens

A published Site or a running Server receives an Action capability token at deploy time. createCapabilityClient from @arg/sdk/server uses that token on the app server without turning it into an account credential:

import { createCapabilityClient } from "@arg/sdk/server";

const arg = createCapabilityClient({
  token: process.env.ARG_ACTION_TOKEN!,
  integrationToken: process.env.ARG_INTEGRATION_TOKEN, // optional
  workspaceId: process.env.ARG_WORKSPACE_ID!,
});
const catalog = await arg.actions.list();
const receipt = await arg.actions.run("file_read", { path: "notes.md" });
const contacts = await arg.integrations.proxy("crm", "/objects/contacts", { method: "GET" });

The capability client covers Action discovery, schema, execution and run lookup, plus integrations.proxy when a separate integration token is supplied. It cannot reach chats, workspace discovery or the other resources: those need an account, and a capability token is not one. Its principal, read scope, expiry and revocation are exactly what the token carries. Never return either token to a browser; the hosted frontends guide shows how a Site’s own frontend reaches the SDK through a gateway instead.

A CI example

- name: Publish the nightly report
  env:
    ARG_API_KEY: ${{ secrets.ARG_API_KEY }}
    ARG_WORKSPACE_ID: ${{ vars.ARG_WORKSPACE_ID }}
  run: node scripts/publish-report.mjs

import { createServerClient } from "@arg/sdk/server";

const arg = createServerClient({
  workspaceId: process.env.ARG_WORKSPACE_ID,
  auth: { kind: "api-key", key: process.env.ARG_API_KEY },
});
try {
  await arg.fs.write("/reports/nightly.md", report);
  await arg.notifications.sendToMe({
    title: "Nightly report ready",
    body: "See /reports/nightly.md",
    channels: ["in-app"],
  });
  const turn = await arg.chat.start("Summarize /reports/nightly.md in three bullets");
  console.log("started chat", turn.chat_id);
} finally {
  arg.dispose();
}

Getting started

Building with agents

Core concepts

Apps

Arg SDK

Integrations

Command line

Recipes & patterns

Changelog

Servers and CI

Options

What the client serves

Requests, deadlines, cancellation

The legacy client underneath

Advanced file transfers

Sites and Servers with their own tokens

A CI example

​Options

​What the client serves

​Requests, deadlines, cancellation

​The legacy client underneath

​Advanced file transfers

​Sites and Servers with their own tokens

​A CI example

Options

What the client serves

Requests, deadlines, cancellation

The legacy client underneath

Advanced file transfers

Sites and Servers with their own tokens

A CI example