Workspaces

Workspaces are isolated cloud environments with persistent file storage and a sandboxed execution environment for running code.

What is a workspace?

A workspace is:

A persistent volume for storing files (code, data, documents)
A sandbox environment where you can run bash commands, execute scripts, and start services
The unit an agent works in - point a run at a workspace and it can read, write, and execute there
Scoped to a user (personal workspace) or an organization (shared workspace)

Creating a workspace

Personal workspace

curl -X POST https://api.arg.ai/api/workspaces \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Project"}'

Organization workspace

curl -X POST https://api.arg.ai/api/organizations/org_123/workspaces \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Team Project"}'

POST /api/workspaces requires a user principal, so a service-account key gets 403. Create the workspace under an organization instead - that route accepts both. See Unattended runs.

Pass storage_region at creation to choose where the workspace’s files live: wnam, enam, weur, eeur, apac, or oc. It cannot be changed afterwards.

Listing workspaces

# Every workspace this credential can access
curl https://api.arg.ai/api/workspaces \
  -H "X-API-Key: YOUR_API_KEY"

# Workspaces in one organization
curl https://api.arg.ai/api/organizations/org_123/workspaces \
  -H "X-API-Key: YOUR_API_KEY"

Updating a workspace

curl -X PATCH https://api.arg.ai/api/workspaces/ws_123 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed Project", "versioning_enabled": true}'

Field	Description
`name`	New name.
`icon_emoji`	Emoji shown beside the workspace. Send `null` to clear it.
`versioning_enabled`	Keep previous versions of every file - see Files.
`allow_external_sharing`	Allow share links to people outside the organization.

Who can see it

curl -X PATCH https://api.arg.ai/api/workspaces/ws_123/visibility \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"visibility": "restricted"}'

Visibility	Who can see the workspace
`org`	Everyone in the organization, at the access their role grants.
`restricted`	Only people explicitly granted access.
`private`	Only its owner.

Visibility applies to organization workspaces; a personal workspace cannot change it. Managing a workspace this way needs manage access to that specific workspace, not just an organization role.

Deleting a workspace

Deleting a workspace permanently removes all files. This cannot be undone.

curl -X DELETE https://api.arg.ai/api/workspaces/ws_123 \
  -H "X-API-Key: YOUR_API_KEY"

Running commands

Execute bash commands in the workspace sandbox. The workspace files are mounted at /ws in the sandbox, which is also the working directory.

curl -X POST https://api.arg.ai/api/workspaces/ws_123/tools/run-bash \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "ls -la"}'

Response:

{
  "status": "completed",
  "stdout": "total 4\ndrwxr-xr-x 2 user user 4096 Aug 13 00:00 .\n",
  "stderr": "",
  "duration_ms": 1234
}

status is completed or failed - a non-zero exit is failed, not an HTTP error. See Tools for the rest of the sandbox surface, including named sandboxes and the 10-minute command limit.

Getting started

Building with agents

Core concepts

Apps

Arg SDK

Integrations

Command line

Recipes & patterns

Changelog

What is a workspace?

Creating a workspace

Personal workspace

Organization workspace

Listing workspaces

Updating a workspace

Who can see it

Deleting a workspace

Running commands

​What is a workspace?

​Creating a workspace

​Personal workspace

​Organization workspace

​Listing workspaces

​Updating a workspace

​Who can see it

​Deleting a workspace

​Running commands

What is a workspace?

Creating a workspace

Personal workspace

Organization workspace

Listing workspaces

Updating a workspace

Who can see it

Deleting a workspace

Running commands