--- title: "Using Self-Hosted Machines" canonical: https://trickest.com/docs/using-the-app/private-execution-networking/using-self-hosted-machines description: "Attach your own Docker hosts as self-hosted workers and run workflows on your infrastructure." --- # Using Self-Hosted Machines ## Overview This guide walks through connecting your own machines to Trickest: creating a self-hosted fleet, attaching a machine to it, and confirming it is ready to execute workflows. For what a self-hosted machine actually is and what the agent can access on your machine, see [Self-Hosted Machines](/docs/key-concepts/self-hosted-machines). On the [Community plan](/docs/key-concepts/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: ```bash 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](/docs/developer-tools/cli/fleet#trickest-attach) 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: ```bash 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: ```bash 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 haven't executed any jobs for 30 days, even if the agent is still connected. 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. ## Related What the agent is, what it can access, and machine lifecycle. Inspect fleets and machines from the trickest CLI. --- _Markdown source of https://trickest.com/docs/using-the-app/private-execution-networking/using-self-hosted-machines._