Skip to main content
One daemon on a server runs the campaigns. You drive it from any machine with the same piloop CLI.

​
Start the daemon

On the server, in $PILOOP_HOME/config.toml:
tls = "proxy" says that a reverse proxy or an SSH tunnel ends TLS in front of the daemon. To end it in the daemon, name a certificate: tls = { cert = "<cert.pem>", key = "<key.pem>" }. Only a loopback address may go without tls. To keep the daemon running, install its service unit.

​
Give each caller a token

The token prints once. read reads, act also acts on campaigns and sets their secrets, and admin also sets the home’s secrets and tokens. worker is for workers. piloop token revoke laptop ends a token.

​
Point the CLI at the server

On your laptop:
Each command that calls the API now asks the server: status, inbox, idea, message, pause, secret and the others. Commands that open the database, such as piloop sql, history, attach and worker list, refuse: run them on the server. For a certificate that your system does not trust, set SSL_CERT_FILE.

​
Register a repo by its URL

The server clones the repo, registers it, and measures HEAD as the baseline:
"name" next to "clone" registers it under another name. For a private repo, send a token that the host accepts. The clone uses it, and the server keeps it nowhere:
Or store the token as a secret of the home, with an admin token, and name it:

​
Give agents their model credentials

An agent on the server has no login of yours. Store the key as a secret of the campaign:
Then name it in the campaign’s piloop.toml:
For a Claude subscription, claude setup-token prints a token: store it as CLAUDE_CODE_OAUTH_TOKEN instead. For a model gateway, see Model access.

​
Run the orchestrator on the server

Let piloop launch the orchestrator on news, in piloop.toml:
Then talk to it from your laptop:
The message launches it on a worker, like any agent. Its answer is in piloop inbox.

​
Run agents on more machines

A worker on another machine takes the jobs of its pool. Give the pool its slots, and serve the CAS:
On the worker:
To have the server start and stop workers itself, on Modal or your own platform, give the pool a provisioner. Workers has the worker’s config.toml, capacity and faults.

​
Behind an authenticating proxy

When a proxy already checks every caller, such as Envoy’s ext_authz or an oauth2-proxy, let it be the only check:
piloop then reads who the caller is from the headers that the proxy stamps, and refuses its own tokens. On your laptop, set PILOOP_HTTPS_TOKEN to the credential that the proxy accepts. Workers need a rule of their own: Behind an authenticating proxy.
Whoever reaches listen directly can claim any identity. Let only the proxy reach it.