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.

Desktop workspaces showing Harbor Shop on main

Mobile workspaces showing Harbor Shop

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 shows workspace identity and Server-owned CPU, memory, storage, and process totals. Branch switching, Fetch, Pull, and Push live at the top of the Git tab.

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, and it stays available after the first workspace exists. Tick Start a review workspace at this revision to clone a disposable copy at a branch, tag, or commit without touching your own checkout. Each row can be removed.

  2. Clone into the source clones directory

    The result is registered so it appears in the workspace list on every connected client. Review workspaces are labelled separately from your own workspaces. Refresh keeps the same workspace and can move it onto a different branch, tag, or commit.

  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 or revision 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. A review workspace uses its own directory, so it never overwrites an existing checkout.

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 an ordinary managed clone unregisters it from Agent-Up and leaves the clone on disk. Removing a review workspace also deletes its clone directory, allocated ports, and browser profile.

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. Open Demo to try the product

    Desktop and Mobile always list a built-in Demo server. Desktop shows the connect picker on every launch before talking to a local Server. It is sample state inside the client, not a running Agent-Up Server.

  2. Connect with the Server URL

    Saved servers stay on the client; only one is active. Sign-in follows that Server's authentication.mode.

  3. Use HTTPS off loopback

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

  4. 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 signed-in Server and that Server URL with Logout. Each workspace has a bottom bar with Apps, Git, Agents, and Settings. Settings lists capability modules. 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 definition to the Server: identity, legacy applications / desktopApplications / services, and every other root array as a runtime section. The Server binds those arrays to enabled runtime-kind modules. 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.