WorkspacesAvailable
Workspaces
A workspace is the unit of isolation. AgentUp.Server owns identity, start/stop, clones, and login. Desktop, Mobile, CLI, and MCP clients display that state and request actions. They do not keep authoritative copies.
Packaged installations run agent-up-server on http://localhost:5000; the repository launch profile uses http://localhost:5001.
Register or start from
agent-up.jsonUse the returned workspace id
Inspect status only when the user asked
Tool
start_workspace
Orchestration MCP
/mcp/orchestration exposes Streamable HTTP and legacy SSE at /mcp/orchestration/sse plus /mcp/orchestration/message. It owns workspace tools, workspace resources, and Agent-Up context resources.
Resources
context
schema
list
one
start_workspace
Registers or updates a workspace from its
agent-up.json, then starts it. If the file is missing, it tells the agent to read the user configuration guide, search for an existing file, or ask before creating one.stop_workspace
Stops a registered workspace by workspace ID or worktree path.
get_workspace_status
Returns a selected workspace status or all workspace statuses. Use only for explicit status questions, already-running workspace inspection, or when
start_workspaceoutput is unavailable.list_workspaces
Lists registered workspaces. Use only when choosing among existing workspaces or answering an explicit list-workspaces question.
get_agent_up_context
Returns concise Agent-Up operating rules for AI agents.
get_workspace_diagnostics and get_workspace_console are documented on Diagnostics. get_agent_up_json_format is documented on Configuration.
Authentication and network boundaries
The REST API uses authentication by default for every REST endpoint unless the endpoint explicitly opts out. GET /api/auth/status and POST /api/auth/login are anonymous so Desktop, Mobile, and other clients can decide whether to display sign-in.
Keep in view
Password
Mode
Login
Status
Connection
Entitlements
Lifetime
AGENTUP_AUTH_MODE selects how credentials are validated:
localAdministrator(default):AGENTUP_ADMIN_PASSWORDforPOST /api/auth/login, which returns an in-memory bearer token.externalBearer: login is rejected. Present a signed JWT whoseiss,aud, and HMAC key matchAGENTUP_EXTERNAL_ISSUER,AGENTUP_EXTERNAL_AUDIENCE, andAGENTUP_EXTERNAL_SIGNING_KEY. Optional claims:workspace,tenant, and repeatedpermissionsvalues. Aworkspaceclaim binds the caller to that workspace id. Protected operations require the matchingpermissionsclaim; a token with none can still readGET /api/entitlements.disabled, orAGENTUP_AUTH_DISABLED=true: REST authentication is off.
GET /api/connection returns anonymous connection metadata: kind (selfHosted), workspacePresentation (serverScoped), and authentication (mode, prompt, identifierRequired). Clients use mode and prompt to render sign-in; they must not infer capabilities from kind. localAdministrator is a password form. browserSso opens the server's /api/auth/sso start URL in a browser. The OSS Server never emits browserSso. Examples/browser-sso is a runnable identity front door that does, so Mobile can be exercised against that contract. identifierRequired is unused.
GET /api/entitlements returns the authenticated permission document. Feature keys are operation permissions (workspace.read, agent.prompt, git.write, and the rest of the Server operation set). A self-hosted Server always returns source: selfHosted, edition: community, billing: free, and every operation available: true. Clients render this document; they must not branch on edition names.
The Server starts even when AGENTUP_ADMIN_PASSWORD is unset. REST routes remain protected in that mode, but local administrator login cannot succeed until the password is configured.
For local development, copy .env.example to .env in the repository root. Server, Desktop, and CLI load that file on startup when present. Existing shell environment variables are not overridden.
Set AGENTUP_AUTH_DISABLED=true to run without REST authentication. Desktop and Mobile query authentication status and skip their login UI in that mode.
Desktop and Mobile reject remote http:// Server URLs for administrator login and require HTTPS outside loopback hosts.
Service hosting
Packaged installations run AgentUp.Server as the local agent-up-server service.
Adapters
macOS
Windows
Ubuntu
NixOS
Packaged services bind to http://127.0.0.1:5000 by default. Service definitions that automatically restart the Server must throttle restart attempts to at least 5 seconds so a bind failure cannot create a tight restart loop.
AgentUp.Tray is the installed Server companion. It keeps a login autostart entry and heartbeats POST /api/tray/heartbeat so the Server knows a workstation session is present.
POST /api/service/restart and POST /api/service/shutdown are authenticated service-control routes for the packaged agent-up-server process. They are not workspace orchestration.
Managed source clones
The SourceClones slice owns repositories Agent-Up clones for itself. POST /api/source-clones takes a repository and a branch, validates both, clones into the source clones root, and registers the resulting workspace through the Workspaces controller boundary. GET /api/source-clones/root reports the configured root.
The root comes from AGENTUP_SOURCE_CLONES_ROOT and otherwise defaults to a sources directory under the Server data directory. Remotes are restricted to http, https, ssh, and git URLs plus the user@host:path form. Local file:// and transport-helper remotes are rejected.
GET /api/workspaces/{workspaceId}/overview returns workspace identity plus Server-measured worktree storage and local-process CPU and memory totals. Docker application containers are not included in the CPU and memory figures.
POST /api/workspaces/tutorial/cleanup is a Desktop onboarding support endpoint. It stops and removes every registered workspace when the first-run tutorial starts.
Desktop and Mobile clients
Desktop displays workspaces, connects to one Server at a time, and may remember additional Server URLs with their login tokens. Switching Servers drops Desktop-local workspace and browser state. The workspace list + button posts to the Server's source-clones endpoint. Desktop does not clone, validate remotes, or choose a destination directory.
On first start, Desktop shows a required setup tutorial over the normal application shell unless the user has already completed or skipped it. Native Desktop E2E tests set AGENTUP_SKIP_FIRST_RUN_TUTORIAL=1. Installed Desktop artifacts connect to http://localhost:5000 by default.
Mobile displays Server-owned workspace state and submits requests. It subscribes to GET /api/workspaces/events so Apps-tab start/stop controls and status LEDs follow Server lifecycle and port health. Route entrypoints stay under src/app/; product UI lives under src/features/. Remote servers must use HTTPS; loopback HTTP remains for local development. When EXPO_PUBLIC_RECOMMENDED_SERVER_URL or AGENTUP_RECOMMENDED_SERVER_URL is set, that connection is always listed first and cannot be removed. If login is required, Mobile reads GET /api/connection for the sign-in prompt and whether to open /api/auth/sso or the password form. The workspace list renders GET /api/entitlements as an edition card keyed by operation permissions and hides Add workspace when workspace.create is unavailable. Run ./au-debug test mobile before submitting mobile client changes. Maintainer visual comparison uses au-debug.