Servers

A server runs a command in the workspace sandbox and puts an HTTPS URL in front of it. Use it to preview a web app, expose an API you just generated, or host a service that other systems call - without deploying anything of your own.

Servers are for a running process. To publish static or built output at a stable subdomain instead, use Sites.

export ARG_API_KEY="arg_live_your_key_here"
export ARG_API="https://api.arg.ai"

Start a server

curl -sS -X POST "$ARG_API/api/tunnels" \
  -H "X-API-Key: $ARG_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "'"$WS"'",
    "command": "python3 -m http.server 8080",
    "port": 8080,
    "name": "Preview",
    "timeout": 300
  }'

{
  "tunnel_id": "…",
  "workspace_id": "…",
  "status": "starting",
  "url": "https://….arg.ai",
  "port": 8080,
  "name": "Preview",
  "created_at": "2026-08-13T00:00:00Z",
  "expires_at": "2026-08-13T00:05:00Z"
}

Field	Description
`workspace_id`	Workspace to run in. Required.
`command`	The command that starts the server and keeps running. Required.
`port`	Port it listens on, 1024 to 65535. Required.
`exec`	A setup command to run once first, such as an install step.
`name`	Display name.
`timeout`	Seconds before shutdown. Pass `0` to keep it running indefinitely.
`access`	`public`, `workspace`, or `personal`. Defaults to `public`.

Both command and exec also accept an array of strings when you would rather not quote a shell string. The workspace is mounted at /ws in the sandbox, so your code is already there.

Who can reach it

`access`	Who
`public`	Anyone with the URL.
`workspace`	People who can access the workspace.
`personal`	Only the person who launched it. Requires a human launcher, not a service account.

A non-public server needs a minted URL rather than its bare address:

curl -sS -X POST "$ARG_API/api/tunnels/$TUNNEL_ID/access-url" \
  -H "X-API-Key: $ARG_API_KEY" -H "Content-Type: application/json" \
  -d '{"presentation": "top-level"}'

The returned URL is short-lived and scoped to the caller. Use "presentation": "embed" when it will be loaded inside a frame.

Limits

Limit	Value
Active servers per workspace	3
Default timeout	5 minutes
Maximum timeout	30 minutes, or no expiry with `timeout: 0`

Exceeding the server limit returns 429.

Manage servers

# List
curl -sS "$ARG_API/api/tunnels?workspace_id=$WS" -H "X-API-Key: $ARG_API_KEY"

# Inspect one
curl -sS "$ARG_API/api/tunnels/$TUNNEL_ID" -H "X-API-Key: $ARG_API_KEY"

# Stop it, and its sandbox
curl -sS -X DELETE "$ARG_API/api/tunnels/$TUNNEL_ID" -H "X-API-Key: $ARG_API_KEY"

Status is one of starting, running, stopped, or failed.

Calling connected integrations from a server

A server can call a connected provider without ever holding that provider’s credential. Declare a portable alias in the .server file:

{
  "command": "node server.js",
  "port": 8080,
  "integrations": {
    "github": { "provider": "github" }
  }
}

Never put a connection id, a provider credential, or a provider base URL in the .server file. You bind each alias to a real connection when you explicitly launch the server, and integration-enabled files never launch on their own. Launching through the API means sending those bindings with the request. The declarations stay in the file:

curl -sS -X POST "$ARG_API/api/tunnels" \
  -H "X-API-Key: $ARG_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "'"$WS"'",
    "command": "node server.js",
    "port": 8080,
    "bindings": [
      { "alias": "github", "provider": "github", "connectionId": "connection_123" }
    ]
  }'

Every declared alias needs exactly one matching binding. Duplicate aliases, provider mismatches, and connections the launching principal does not own are rejected. A binding keeps the connection’s existing owner: a user-owned connection runs only as that user, and a service-account-owned connection only as that service account. Launching never hands a person’s credential to a service account. The running process receives a revocable, server-scoped broker URL and token as ARG_INTEGRATIONS_URL and ARG_INTEGRATIONS_TOKEN. Append the alias and a relative provider path, and send the token as a bearer credential:

const url = `${process.env.ARG_INTEGRATIONS_URL}/github/repos/acme/widgets/issues`;
const response = await fetch(url, {
  headers: {
    Authorization: `Bearer ${process.env.ARG_INTEGRATIONS_TOKEN}`,
    Accept: "application/vnd.github+json",
  },
});

if (!response.ok) {
  throw new Error(`GitHub request failed: ${response.status}`);
}

The broker validates the live server, the alias, the provider, the connection’s owner, and its revocation state before adding the credential and forwarding the request. Use relative paths only; never send a provider base URL.

Never log, persist, or return ARG_INTEGRATIONS_TOKEN. It is narrower than the provider credential, but it can use the bound connection for as long as the server is up. Server URLs can be public, and collaborators can change code in the live workspace, so both inbound requests and later edits can exercise that authority until the server is stopped. Give unattended servers the narrowest provider scopes available.

Tools - one-off commands, when you do not need a long-lived process
Integrations - connecting the accounts a binding points at
Servers API reference - every field

Getting started

Building with agents

Core concepts

Apps

Arg SDK

Integrations

Command line

Recipes & patterns

Changelog

Start a server

Who can reach it

Limits

Manage servers

Calling connected integrations from a server

​Start a server

​Who can reach it

​Limits

​Manage servers

​Calling connected integrations from a server

​Related

Start a server

Who can reach it

Limits

Manage servers

Calling connected integrations from a server

Related