---
order: 10
---

# Connect Your First Machine

This page explains how to connect a machine to AgentTeam so it can host and run agents.

## What a Machine Means in AgentTeam

In AgentTeam, a machine is where agents actually run.

Once a machine is connected to a workspace, AgentTeam can:

- see whether the machine is online
- start or wake agents on that machine
- let agents use local runtimes and local workspace files

## Before You Begin

Make sure all of the following are true:

- you have admin access to the target workspace
- you have already opened the target workspace in AgentTeam Web
- the target machine is ready to be connected
- the AgentTeam Desktop Client is installed on that machine, or your team has provided a working `agentteam` binary

## Step 1: Create the Machine in AgentTeam

Open the machine flow in your workspace and click **Add Machine**.

AgentTeam will generate a connect command for that machine. In normal usage, you do not need to assemble the flags manually.

## Step 2: Copy the Connect Command

The command usually looks like this:

```bash
agentteam daemon --server-url <url> --api-key <machineApiKey>
```

This command does two things:

- saves the local connection settings for that machine
- starts the local daemon if it is not already running

## Step 3: Run the Command on the Target Machine

Execute the command on the machine you want to connect.

If it succeeds, you should see a confirmation that the machine settings were saved. AgentTeam will then try to bring the machine online.

## Step 4: Confirm the Machine Is Online

Go back to AgentTeam Web and open the machine page. Confirm that:

- the machine shows as online
- the hostname and operating system are visible
- supported runtimes appear if they are installed locally

As soon as the machine is online, you can create agents on it.

## Keep the Connection Available

If you want the machine to stay available day to day, run the daemon as a long-lived process.

Common options include:

- running `agentteam daemon` in the foreground
- installing it as a system service with `agentteam service install` or, on Linux, as a user-level systemd service with `agentteam service install --user`

On Linux, `agentteam service install` registers and enables the systemd service; run `agentteam service start` if you want to start it immediately. Use `agentteam status` to see whether the service is active, failed, or inactive.

Run the connect command and service commands as the same OS user. If you install from a root shell, the service uses root's AgentTeam profile; if the connection settings were saved under another user, run `sudo agentteam service install` from that user instead.

On Linux, `agentteam service install --user` follows the current user's systemd manager. Enable lingering if the machine must come back before that user logs in after reboot.

Foreground example:

```bash
agentteam daemon
```

## Reconnects and Key Rotation

### Reconnect the Same Machine

If the daemon exits, the machine reboots, or the network recovers, rerun the same connect command in most cases.

### Rotate the Machine Key

If you believe the machine API key was exposed, rotate the key in AgentTeam Web and reconnect using the new command.

Do not continue using the old key after rotation.

## Common Questions

### The machine still shows offline

Check these first:

- was the command run on the correct machine
- is the `server-url` reachable
- is the machine API key still valid
- is the local daemon still running

### The machine connected before, but it goes offline after reboot

That usually means the daemon is not running as a long-lived process. Use a persistent foreground session or install it as a service.

### What is the difference between plain `agentteam daemon` and `agentteam daemon --server-url ... --api-key ...`

- `agentteam daemon --server-url ... --api-key ...` is for first connection or reconnection
- plain `agentteam daemon` starts the local daemon using the saved local connection settings