Quickstart

Get Swarm running

Install the local daemon, start it as an always-on service, then connect your first client and finish onboarding.

Install Swarm.

Install the daemon, choose how it starts, then verify it is running.

Run the installer

Linux x86_64 and WSL Ubuntu are available now through the latest-release installer. You do not need to clone the source repository to install Swarm.

curl -fsSL https://swarmagent.dev/install | sh

Choose system service when prompted

The installer prints an install plan, then asks how Swarm should start. Choose the service option to install, enable, and start swarm.service so Swarm stays running.

1 Service Recommended

Runs Swarm as an always-on background service.

2 Manual Start yourself

Install Swarm, but manage start/stop manually.

3 Cancel Exit install

Stop the installer without setting up Swarm.

Verify the daemon

After installation, check that the service is installed, active, and healthy.

swarm status

Connect a client.

Swarm provides two ways to connect a client to the running service.

Terminal

Open the terminal client in your project directory.

swarm

Desktop

Open the Swarm desktop client, or visit the local desktop URL.

swarm --desktop

127.0.0.1:5555

The terminal client opens in the directory where you launch it. Run swarm from your project root when you want the terminal client attached to that project.

The desktop listener defaults to 127.0.0.1:5555. Change desktop_port in swarm.conf if you need a different port, then restart Swarm. See Configuration ports.

Onboarding.

Create a user, name this Swarm, and add provider auth.

1. CREATE USER

Create the first local user.

2. NAME SWARM

Choose a name for this runtime.

3. Add auth

Paste a provider API key.

Why create a user?

Sessions, workspaces, permissions, and teams attach to a stable account.

What is a Swarm name?

A Swarm name identifies this runtime instance.

What auth is needed?

Supported AI providers: Codex, Anthropic, Fireworks, Google, and OpenRouter.

Tip: Run /auth on desktop or terminal to add another provider, and /agents to control your agents.

Create your first workspace.

After onboarding, create a workspace from the client you plan to use first.

Terminal client

The terminal client starts from the directory where swarm is launched.

cd ~/your-project && swarm

This attaches the terminal client to that project context.

Desktop client

You are now in the desktop launcher after onboarding.

Open desktop.
Choose or create a workspace from the workspace picker.
Select the project path.

The terminal path is directory-first. The desktop path is launcher-first. Both create workspaces against the same local Swarm runtime.

Tip: In either terminal or desktop, run /workspace to open workspace controls and manage the current workspace.

What’s next?

Use this page as the bridge from install into first real use.

Start with a local workspace

Create one workspace for the project you want Swarm to work on.

Add provider auth

Add only the provider credentials you plan to use first.

Connect a local container

Keep local work simple, then isolate riskier project tasks when needed.

Move to remote hosts later

Start locally first, then move heavier or longer-running work off your machine.