Skip to main content

WorkspacesAvailable

Workspaces

A workspace is the unit of isolation for a developer or agent session. Start it from the directory that contains agent-up.json.

It is identified by project path. It may include Git metadata, a browser profile, Docker infrastructure, running processes, an allocated port range, diagnostics, and event history.

Non-Git paths still work and display as not on a git branch. Agent-Up can also clone a repository for you and register the result.

  1. Add agent-up.json at the repository root

  2. Start the workspace

  3. Switch among isolated sessions

Command

agent-up start

Where it differs

CLI

From the directory that contains agent-up.json.

Desktop

The workspace list + control clones a repository at a branch and registers it.

Mobile

The same + control lives on the sidebar workspace list. There is no Workspaces tab.

Worktree model​

The workspace identity is the project path. When that path is a Git repository or worktree, Agent-Up records the repository root, branch, and commit. When no Git repository exists, the workspace still works and displays not on a git branch.

Git worktrees are the recommended model for AI agents working in the same repository because they preserve separate branches, running applications, browser sessions, and validation state.

Where it differs

Desktop

The Overview tab has a branch dropdown for local and remote-tracking branches, Fetch/Pull/Push, plus workspace identity and Server-owned CPU, memory, storage, and process totals.

Mobile

Those Git controls live on the workspace Git tab, beside Apps and Agents.

Managed source clones​

Agent-Up can manage the clone itself instead of only registering a checkout you created.

  1. Ask for a repository and branch

    Both the Desktop workspace list and the Mobile sidebar have a + button.

  2. Clone into the source clones directory

    The result is registered so it appears in the workspace list on every connected client.

  3. Keep isolation

    Clones created this way behave like any other workspace: they get their own port range, processes, browser profile, and diagnostics.

The repository must be an http, https, ssh, or git remote URL, or the user@host:path form. The branch must already exist on the remote. Agent-Up refuses a clone when a directory with the repository's name already exists under the source clones directory.

The source clones directory defaults to a sources folder inside the Server data directory. Set AGENTUP_SOURCE_CLONES_ROOT in the Server environment to keep managed clones somewhere else, such as a larger disk.

Removing such a workspace unregisters it from Agent-Up. It does not delete the clone from disk.

Runtime isolation​

Workspace isolation prevents collisions between concurrent development sessions.

Each workspace owns

Ports

Its own contiguous port range

Processes

Its own process group

Docker

Its own Docker lifecycle

Browser

Its own browser profile

Diagnostics

Its own diagnostics stream

Switching workspaces​

Switching workspaces should restore the relevant running applications and browser state without forcing developers or AI agents to recreate tabs, reauthenticate, or restart unrelated services.

Connect and login​

  1. Connect with the Server URL

    Saved servers stay on the client; only one is active.

  2. Use HTTPS off loopback

    Remote servers must use HTTPS. Loopback HTTP remains for local development.

  3. Expect a clean client switch

    Switching servers drops that client's local workspace state.

Where it differs

Mobile

After connect, the sidebar lists workspaces for the active Server. Each workspace has a bottom bar with Apps, Git, and Agents. The Apps tab start/stop control requests the Server-owned lifecycle and shows live health.

CLI workspace commands​

start searches the current directory and its parents for agent-up.json, then pushes the workspace and application definitions to the Server. The directory containing agent-up.json is the workspace root. Running start again from the same workspace updates the existing workspace in place.

agent-up start --server http://localhost:5001

Other commands

stop

Stops the current workspace

list

Lists workspaces the Server knows

status

Shows workspace status

clear

Stops and removes all known workspaces

auth authenticates the CLI with a Server that requires the admin password. Tokens are stored locally per server URL. auth commands always require an explicit --server argument. They do not fall back to repository .env values or AGENTUP_SERVER_URL.

agent-up auth login --server http://localhost:5001 --password "$AGENTUP_ADMIN_PASSWORD"

Omit --password to enter the admin password interactively. Use auth status to check whether authentication is required, and auth logout to remove the stored token.

When invoking with dotnet run, pass CLI arguments after --. Use http://localhost:5001 when running Server from the repository launch profile.

dotnet run --project AgentUp.CLI -- start --server http://localhost:5001

Next in this slice

Applications

Processes that run inside a workspace.