> ## Documentation Index > Fetch the complete documentation index at: https://docs.creao.ai/llms.txt > Use this file to discover all available pages before exploring further. # Terminal and Linux servers > Run CREAO Connect without the desktop app: pair a Linux server, board or VM, keep it running as a service, and manage tools and approvals from the terminal. The `creao-connect` command runs the same service as the [CREAO Connect desktop app](https://docs.creao.ai/features/device-connect.md), without a window. Use it to give your CREAO agents tools on a machine you reach over SSH. It suits: * **Linux servers and VMs**, such as a build box, a home server or a cloud instance. * **Single-board computers**, such as a Raspberry Pi 4 or 5 running 64-bit Linux. * **Disposable sandboxes**, where agents may run anything because the machine is thrown away afterwards. * **People who live in SSH or tmux**, with a full-screen terminal UI for status, tools and approvals. * **AI agents on the server**, such as a coding agent, which can operate `creao-connect` from its own shell. > [!NOTE] > > CREAO Connect is in early access. If you don't see **Devices** in CREAO, it isn't enabled for your account yet. ## Requirements * **64-bit Linux** on x64 or arm64. Builds exist for glibc distributions (Debian, Ubuntu, Fedora and similar) and for musl distributions (Alpine). * **bash** at `/bin/bash`. Some install steps from the CREAO catalog run through it. * **On Alpine and other musl systems**, install the C++ runtime first: ```bash theme={null} apk add libstdc++ libgcc bash ``` ## Get the binary The Linux build is a single executable with no other dependencies. It isn't offered as a download in CREAO yet: during early access it's provided on request. Email [support](https://docs.creao.ai/support.md) from your early-access account and say which build you need: x64 or arm64, glibc or musl (Alpine). Then put it on your `PATH`: ```bash theme={null} sudo install -m 755 creao-connect /usr/local/bin/creao-connect creao-connect --version ``` Run `creao-connect help` for every command, and `creao-connect help ` for its options. ## Pair the machine **1. Start pairing** Give the machine a name your agents will see: ```bash theme={null} creao-connect pair --name build-server ``` The command prints a pairing code and an approval link, then waits. **2. Approve it in CREAO** Open the link in a browser where you're signed in to CREAO, or open **Devices** → **I have a pairing code** and enter the code. Check that the name matches, then click **Approve device**. Codes expire after 10 minutes. If a code expires, run `pair` again. **3. Start the service** Once you approve the code, `pair` exits. The machine is paired, but agents can reach it only while the service runs. See [Keep it running](#keep-it-running). For a VM or container you'll throw away, add `--ephemeral`. See [Ephemeral devices](#ephemeral-devices). > [!TIP] > > `creao-connect tui` can pair too. On a machine that isn't paired yet, it starts with pairing, then offers to start the service for you. ## Keep it running The service holds the connection to CREAO and runs what your agents ask for. Run it in the foreground inside tmux or a container: ```bash theme={null} creao-connect daemon ``` It logs to the terminal and to `~/.creao-connect/logs/daemon.log`. To keep it running after you log out, use a systemd user service. Create `~/.config/systemd/user/creao-connect.service`: ```ini theme={null} [Unit] Description=CREAO Connect After=network-online.target Wants=network-online.target [Service] ExecStart=/usr/local/bin/creao-connect daemon Restart=always RestartSec=5 [Install] WantedBy=default.target ``` Then enable it and let it run without an open session: ```bash theme={null} systemctl --user daemon-reload systemctl --user enable --now creao-connect loginctl enable-linger "$USER" ``` * **Pair before you enable the service.** A service that isn't paired exits with an error, and systemd keeps retrying it. * **Use `Restart=always`.** The service exits on purpose when you restart it from the terminal UI, and expects to be started again. * **After you unpair or revoke the device**, the service stops. Run `systemctl --user disable --now creao-connect` until you pair the machine again. > [!NOTE] > > `creao-connect` keeps its settings and pairing in `~/.creao-connect`. To use another folder, set `CREAO_CONNECT_HOME` the same way for every command and for the service. Keep that path short and on a local disk. ## The terminal UI Run `creao-connect tui` in SSH or tmux for a full-screen view of the machine: | View | What you do there | | - | - | | **Home** | Status, device name, how many tools it offers, what needs your attention and recent activity | | **Tools** | Set **Off**, **Ask** or **Allow** per tool, for **Agents in cloud** and **Local workers** | | **Workers** | Installed Local Workers, and whether your agent may start each one | | **Activity** | The log of what ran and who allowed it, and active temporary permissions you can revoke | | **Install** | Paste an install link from the CREAO catalog and follow its steps | | **Settings** | Folders for file tools, restart the service, unpair | Press `Tab` / `Shift-Tab` or `1`–`6` to switch views, `r` to refresh, `?` for help and `q` to quit. The service keeps running after you quit. If no service is running, the TUI offers to start one in the background. ![The creao-connect terminal UI Home view for a device named build-server](https://mintcdn.com/creaoagent/m-58ldeOrwH0ia3W/images/connect-tui-home.png?fit=max\&auto=format\&n=m-58ldeOrwH0ia3W\&q=85\&s=18b6d7009fb78446a87b61a723a143d4) The terminal UI's Home view on a paired Linux server. ### Approval prompts in the terminal When a tool set to **Ask** is called, the TUI opens an approval prompt with the same choices as the desktop app: what it applies to, and for how long (**Once**, **1 hour**, **8 hours** or **Always**). | Key | Action | | - | - | | `Enter`, `d` or `Esc` | Deny. `Enter` never allows. | | `a` | Allow, with the scope and duration you chose. It works only after the prompt has been up for a moment, so a key you meant for something else can't approve a call. | | `o` | Turn the tool off for that caller and deny the call. | ![The creao-connect terminal UI showing a permission request to run a terminal command](https://mintcdn.com/creaoagent/m-58ldeOrwH0ia3W/images/connect-tui-consent.png?fit=max\&auto=format\&n=m-58ldeOrwH0ia3W\&q=85\&s=60b21942ae703eb8465fe8250cfe1e2d) An approval prompt in the terminal UI. Enter denies; press a to allow. ### Answer from CREAO You don't need a terminal open to approve. When a prompt is waiting, CREAO shows it on the task card in the chat, on the web and in the phone app, with a notification. If nobody can be asked, a call that needs approval is refused at once instead of waiting. That happens when the terminal UI isn't open and approvals in CREAO aren't available for your account. For a machine nobody watches, decide which tools may run without asking and set exactly those to **Allow**. ## Tool access from the command line Each tool is **off** (not offered), **ask** (waits for approval) or **allow** (runs without asking). Callers are `agent` (your CREAO agents in the cloud), `workers` (all Local Workers) or `worker:` (one worker). Without `--caller`, a setting applies to every caller. ```bash theme={null} # See every provider, its tools and their access creao-connect providers list # Let your cloud agent read system information without asking creao-connect providers set builtin --tool system-info --access allow --caller agent # Make every tool of an MCP server ask again creao-connect providers set github --access ask # Remove a setting so the tool falls back to its default creao-connect providers set builtin --tool bash --access default --caller agent ``` `builtin` is the provider for the built-in tools. A tool set to **off** stays off: no approval, temporary permission or sandbox mode turns it back on. Changes apply right away, without a restart. To decide whether your cloud agent may start a Local Worker, use `creao-connect workers policy --start off|ask|allow`. To list installed workers, run `creao-connect worker list`. ## Add MCP servers ### From the CREAO catalog **1. Get an install command in CREAO** In CREAO, open an MCP server from **Devices** → **Browse MCP servers** and click **Install on a Linux server**. CREAO shows a command under **Run this on your server**. Copy it. **2. Run it on the server** With the service running, paste the command: ```bash theme={null} creao-connect install creao-connect://install/v1/… ``` It walks the same steps as the desktop app: it shows what will be installed and waits for you to confirm, asks for any settings, signs in if needed, and checks that the server answers. Values you type are saved on the machine and are not sent to CREAO. ![The CREAO catalog page for an MCP server showing the Run this on your server command panel](https://mintcdn.com/creaoagent/m-58ldeOrwH0ia3W/images/device-connect-linux-install-command.png?fit=max\&auto=format\&n=m-58ldeOrwH0ia3W\&q=85\&s=2df58e6956dcf218ab827c6db784138d) The server install command in CREAO. Each command works for one device and expires after an hour. * **Keep the command private.** Anyone who runs it on a device paired to your account installs that server there. * **Signing in over SSH.** If the server needs a browser sign-in, the command prints the sign-in link and an `ssh -L` command. Run that `ssh -L` command on the computer with the browser first, then open the link. * **Only Linux-ready entries install here.** Catalog servers that don't support Linux are refused before anything changes. * **Cancelled during sign-in?** The server stays set up but signed out. Run `creao-connect providers auth ` to finish signing in, or `creao-connect providers remove ` to remove it. For scripts and agents, `install` takes: | Option | What it does | | - | - | | `--yes` | Accepts the confirm step and skips pages that need no answer. Review what will be installed before you use it. | | `--answers ` | Pre-fills settings and answers from a JSON file, or from stdin with `-`. | | `--json-lines` | Prints each step as a machine-readable event line and reads answers as JSON lines on stdin. | ### Add one yourself ```bash theme={null} # A local program creao-connect providers add notes --stdio -- npx -y @modelcontextprotocol/server-filesystem /srv/notes # A remote server with browser sign-in (use --no-browser over SSH) creao-connect providers add linear --url https://mcp.linear.app/mcp --oauth creao-connect providers auth linear --no-browser ``` Use `--allow-tool` and `--deny-tool` to limit which tools a server offers, and `providers disable` or `providers remove` to take it out of use. ## Sandbox mode For a disposable machine, sandbox mode turns every **Ask** into **Allow**: ```bash theme={null} creao-connect daemon --dangerously-skip-permissions ``` > [!WARNING] > > In sandbox mode, your agents can run anything on the machine without asking you, including terminal commands that change or delete files. Use it only on a disposable VM or container that holds none of your own data or credentials. * **Some limits still apply.** Tools set to **off** stay off, file tools stay inside their folders, and a worker that isn't ready is still refused. * **It isn't saved.** Sandbox mode lasts only while that service runs. Restart the service without the flag to turn it off. * **It's always visible.** The service prints a warning when it starts, the TUI's Home view shows a banner, every activity entry records that it ran without asking, and the device shows a **Permissions bypassed** badge on the **Devices** page in CREAO. A typical disposable VM runs `pair --ephemeral`, then `daemon --dangerously-skip-permissions`, then `unpair`, or is simply destroyed. ## Ephemeral devices `creao-connect pair --name ci-runner-42 --ephemeral` marks the device as disposable. The approval page says so, and the **Devices** page tags it **Ephemeral**. An ephemeral device disappears from CREAO about an hour after it goes offline. Your agents can't reach it after that, and it no longer counts toward your devices. A device that reconnects before then keeps working. Run `unpair` to remove it at once. ## Check status and activity ```bash theme={null} creao-connect status # pairing and service state creao-connect status --json # the same, as one JSON object creao-connect activity --limit 20 ``` `status --json` reports whether the machine is paired, the device name, and whether the service is running, paused or in sandbox mode. `activity` prints one JSON object per line: what ran, who asked, how it was decided and how it ended. Include `creao-connect --version` when you contact support. ## Unpair ```bash theme={null} creao-connect unpair ``` `unpair` removes the device from CREAO, stops a running service and clears the pairing on this machine. Your settings, MCP servers and workers stay on disk, so pairing again picks them up. You can also remove the device from the **Devices** page in CREAO with **Revoke**. ## Let an AI agent on the server operate it If you run an AI coding agent on the server, it can set up and operate CREAO Connect for you. Have it read the built-in guide: ```bash theme={null} creao-connect skill ``` This prints a usage guide written for agents and matched to the installed version. It covers pairing, running the service, tool access, installs and troubleshooting, with safety rules: you approve the pairing yourself, the agent asks before widening access, and it uses sandbox mode only on disposable machines. The agent should use `--json` and `--json-lines` output rather than parse human-readable text. The terminal UI is for people. ## Troubleshooting | Symptom | What to do | | - | - | | `Not paired` | Run `creao-connect pair --name ` and approve the code in CREAO. | | `error while loading shared libraries: libstdc++.so.6` | You're on a musl system such as Alpine without the C++ runtime. Run `apk add libstdc++ libgcc bash`. | | Calls are refused at once because nobody can approve them | Open `creao-connect tui` to answer prompts, answer from CREAO if it's available for your account, or set the tools you trust to **Allow**. | | A call was refused after a while | The prompt timed out unanswered. Answer sooner, or set that tool to **Allow** for `agent`. | | `status` says the service isn't running, but it is | The service uses a different `CREAO_CONNECT_HOME`. Set the same value for every command. | | The service exits with `could not create the control socket` | The settings folder's path is too long, or it's on a shared or network filesystem. Set `CREAO_CONNECT_HOME` to a short local folder, such as `~/.cc`. | | The service stops right after you revoke the device | That's expected. Pair again to reconnect. | | A worker is refused as not ready | An MCP server the worker needs isn't connected. Check `creao-connect providers list`. | ## Related > [card] [CREAO Connect](https://docs.creao.ai/features/device-connect.md) > > The desktop app for macOS, tool access and approval prompts. > [card] [Security](https://docs.creao.ai/trust-and-safety/security.md#device-connect-security) > > How pairing, approvals and remote answers are protected. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.