Host Server

superset start runs a headless HTTP server that the Paradev desktop app and CLI talk to. It manages workspaces, ports, and agent runs on its machine. The desktop app starts it automatically. On a CLI-only or headless machine, start it yourself.

The desktop app includes the CLI. It installs a ~/.paradev/bin/superset shim on launch, and Paradev terminals add that directory to PATH. In other shells, add ~/.paradev/bin to PATH. On a headless machine, use the standalone installer from Getting Started.

Prerequisites

git and gh need to be on your PATH. git handles clone, worktree, and branch ops; gh handles PR checkout and metadata.

gh auth login

The host server reuses your existing gh auth. For sandboxes or CI, set GH_TOKEN (or GITHUB_TOKEN) instead of running gh auth login. gh picks it up automatically.

Agent CLIs (optional)

To run AI agents in workspaces, install the agent CLIs you want. The host server launches the ones on your PATH:

None are required to start the host server or create workspaces.

Authenticate the Paradev CLI

The host server starts under your Paradev session:

superset auth login

See Getting Started for the full sign-in flow, including API-key auth for CI.

Start the host server

superset start --daemon

Starts the daemon in the background and writes a manifest at ~/.paradev/host/<organizationId>/manifest.json so other clients can find it. Binds to 127.0.0.1 only.

Check its health:

superset status

Keep it updated

Automatic updates are off by default. To turn them on, start the host with --auto-update:

superset start --daemon --auto-update

• --auto-update requires --daemon.
• The first check runs one hour after start, then every hour. A newer release installs, and the host restarts with its health check and rollback. Terminals reconnect after the restart.
• Updates never downgrade the host. A release that fails its health check is skipped on later automatic checks; superset update can still install it.
• The flag applies to a new start only. To change it, stop the host and start it again.

If an update fails with a permission error on superset.update-lock, the host user cannot write the directory that contains the install. The error names the install path, the lock path, and the user. Give that user ownership of the install and its parent directory, or reinstall as that user.

Run it under systemd

On a server, let systemd start the host server at boot and restart it on failure. Run superset start without --daemon so systemd tracks the process:

# /etc/systemd/system/superset-host.service
[Unit]
Description=Paradev host server
After=network-online.target
Wants=network-online.target

[Service]
User=<user>
ExecStart=/home/<user>/superset/bin/superset start
Restart=on-failure
KillMode=process

[Install]
WantedBy=multi-user.target

Keep KillMode=process. Other kill modes stop the terminal daemon, and with it every terminal and agent, whenever the service stops or restarts. The terminal daemon keeps running after the service stops, so the next start picks up the same terminals.

This setup needs a CLI released after 1.30.2. With 1.30.2 and older, systemctl restart hangs until systemd kills the CLI, and the old host keeps running.

sudo systemctl daemon-reload
sudo systemctl enable --now superset-host

To end every terminal and agent too, stop the unit first, then stop the terminal daemon. If you run superset stop while the unit is active, systemd starts the host again.

sudo systemctl stop superset-host
superset stop --terminals

Getting started

Create or adopt a project

A workspace branches off a project: a repo registered with Paradev. Each repo should have one cloud project record, shared across the organization. The first machine to register the repo runs projects create. Every later machine runs projects setup to attach to the existing project.

Check what this machine has (add --host <id> to check another host):

superset projects list

First machine: projects create

If the project doesn't exist yet, clone a remote repo or import an existing local one:

# Clone from a Git URL
superset projects create \
  --name "My Project" \
  --local \
  --clone https://github.com/org/repo.git \
  --parent-dir ~/code

# Or import a repo that's already on disk
superset projects create \
  --name "My Project" \
  --local \
  --import ~/code/existing-repo

The host server clones (or registers) the repo, creates the cloud project record, and ensures the main workspace.

Subsequent machines: projects setup <id>

If another machine already created the project, adopt it. Running create again would register a second, unrelated project for the same repo. Projects are host-owned, so pick the ID from a machine that has it (projects list --host <id>), then:

# Clone the project's repo onto this machine
superset projects setup 47c31b04-… --local --parent-dir ~/code

# Or attach to an existing local checkout
superset projects setup 47c31b04-… --local --import ~/code/repo

The URL for clone mode comes from the cloud project record, so setup doesn't need --clone <url>. setup is idempotent: re-running against a project that's already set up here is a no-op.

Create your first workspace

superset projects list
superset workspaces create \
  --project prj_… \
  --name "fix-login-bug" \
  --branch fix/login-bug

The host server clones the project (if it isn't already on disk), creates a git worktree at the chosen branch, and registers the workspace.

You can also create a workspace from a pull request number:

superset workspaces create \
  --project prj_… \
  --name "review-pr-123" \
  --pr 123 \
  --local

Stop the host server

superset stop

Your terminals and agents keep running in the terminal daemon, and the next superset start picks them up. To end them as well:

superset stop --terminals

Shared state

State lives under ~/.paradev/host/<organizationId>/:

~/.paradev/host/<organizationId>/manifest.json    # endpoint + auth token
~/.paradev/host/<organizationId>/host.db          # local host server DB

The CLI sees a host server started by the desktop app, and the reverse. SUPERSET_HOME_DIR relocates the whole tree.

Command details

For full flags, exit codes, and output shapes:

• superset start
• superset status
• superset stop