Use your own machines

Sessions can run on machines you already have, such as VMs or build hosts, instead of sandboxes Pistis creates. You start one command on each machine, and Pistis sends it sessions. Pistis never starts, stops or deletes your machines.

Before you startCopy Anchor Link

• A Linux machine that can reach your Pistis server over HTTPS
• The pistisd and pi-env programs, copied out of the pistis/pistisd image. Together they read and write files and run commands for Pistis.

Add a machineCopy Anchor Link

1. Open Control center → Workers → Create pool and name the pool, for example vms.
2. Click Create token for the pool, and copy the token. It is shown once.
3. On your machine, run pistisd join with the token:

PISTISD_SERVER=https://pistis.example.com \
  PISTISD_POOL_TOKEN=pwk_… \
  PISTISD_NAME=build-1 PISTISD_SLOTS=1 \
  PISTISD_WORKDIR=/srv/pistis \
  pistisd join

1. Check that the machine shows as connected on the Workers page.
2. Start a session and pick the pool under Run on in the composer. Over the API, set meta.pool.

The session works in /srv/pistis/<request> on that machine. If your machines are outside the Pistis server's network, set workers.relayUrl to the public wss:// address of the relay, the service machines and sandboxes connect to (Configuration).

How sessions are placedCopy Anchor Link

• A session goes to a connected machine in its pool with a free slot.
• With PISTISD_SLOTS above 1, sessions share the machine and its files. Use one slot when sessions must not see each other.
• A machine that drops off gets a few seconds to reconnect. After that, its session moves to another machine in the pool with its files.
• Old work folders are removed once nothing in them has changed for PISTISD_KEEP_DAYS.

In a test with three machines (a checkpoint is the saved copy of a session's files): vm-1 died; the session moved to vm-2 with note.txt (restored from its checkpoint). Then a token was revoked: revoked: vm-3 refused (exit 3), vm-2 cut off.

Remove a machineCopy Anchor Link

• Click Revoke on a pool's token to cut off every machine that joined with it.
• Click Forget to remove an offline machine from the list.
• pistisd join exits with code 3 when its token is refused, and 2 on a bad setting. It retries an unreachable server.