Using Self-Hosted Machines

Overview#

Self-hosted machines are servers, virtual machines, or cloud instances that you connect to the platform to execute workflows on your own infrastructure. They are organized into fleets, and any fleet you create can be selected as the execution target when running a workflow.

On the Community plan, self-hosted machines are the execution target: the platform creates your self-hosted fleet at signup, and a run starts once at least one machine in it is Active.

Trickest supports the following machine types:

• Virtual machines
• Cloud instances
• Bare-metal machines
• macOS devices

Requirements#

Check the host before you attach it:

• OS: Linux on amd64 (arm64 works without official support yet) or macOS. Windows is not supported.
• Docker: a running Docker daemon. Use Docker Desktop on macOS. The Linux installer offers to install Docker when it is missing.
• Network: outbound HTTPS (port 443) to trickest.io, api.trickest.io, quay.io (tool images), and the agent binary host named in the install script. The agent only dials out; it needs no inbound ports.
• Local port: keep port 2201 free. The agent's Docker log driver listens there.
• Data directory: /data on Linux, ~/trickest on macOS. Override with TRICKEST_DATA_DIR.

On Linux the installer registers a trickest-agent systemd service, so the agent survives reboots.

Fast Path: Attach the Machine You Are On#

With a shell on the machine, the CLI does the whole flow:

curl -fsSL https://trickest.io/install.sh | sh
trickest auth login
trickest attach

trickest attach provisions a machine slot in your self-hosted fleet (and creates the fleet when you have none), installs the Trickest Agent on the current host, and waits until the machine reports Active (default timeout 2m). See the CLI Fleet reference for flags such as --name and --timeout.

Connect a Machine in the App#

Open Settings > Infrastructure > Fleet and choose Connect a machine (or Add Machine). The panel walks the same CLI attach flow and listens for the new worker:

1. Run setup on your machine. Docker required; run the commands on the host you want to attach.
2. Machine registers with Trickest. The platform detects the new slot.
3. Agent connects (Docker running). Keep Docker up while attach finishes.
4. New machine online. The machine is Active and ready for runs.

Copy the bash block from the panel and run it on the host. On production it is equivalent to:

curl -fsSL https://trickest.io/install.sh | sh
trickest auth login
trickest attach --wait --yes --api-base https://api.trickest.io

--wait is already the default for trickest attach. --yes skips installer prompts. --api-base points the agent at Hive (https://api.trickest.io in production). Bare trickest attach after login is enough when the CLI already targets production.

The panel polls every 5 seconds and shows Listening for your machine… until the agent is Active. Use Refresh now if the status looks stale.

Having trouble?#

• Docker Desktop (or the Docker daemon) must be running on the host.
• Finish trickest auth login, then re-run attach (include --api-base if the panel showed it).
• Port 2201 busy (often Cursor)? Quit that app, re-run attach (the installer waits up to 2 minutes for the port), then reopen Cursor.
• Machine limit reached? Delete an unused machine in Fleet settings, then attach again.
• Confirm a self-hosted fleet exists under Fleet settings.

Creating a Self-Hosted Fleet#

Navigate to Settings > Infrastructure > Fleet and open the Self-Hosted tab. Click Create Self-Hosted Fleet when you need another fleet. Community accounts skip this: the self-hosted fleet already exists from signup, and the connect panel creates one when none is present.

Provision Without Installing on This Host#

To get the one-time install script for a different host, run:

trickest attach --no-install

That provisions the machine slot and prints the credential exports plus the agent init installer for you to run on the target. Prefer plain trickest attach when you already have a shell on the worker.

Machine Lifecycle and Limits#

• A new machine starts Inactive and becomes Active once its agent connects.
• A self-hosted fleet holds up to 3 machines by default. The same cap bounds run parallelism on that fleet.
• Each machine executes one run at a time and returns to the pool when the run finishes.
• The platform removes machines that stay inactive for 30 days. Re-attach a removed machine from Settings > Infrastructure > Fleet or with trickest attach.
• Delete a machine entry in Fleet settings when you need the slot back; there is no limit on how many times you can create or delete machines.