---
order: 10
---

# Operate the AgentTeam Desktop Client

The AgentTeam Desktop Client runs on the local machine. The simplest way to think about it is: the daemon and CLI entrypoint that keep this machine connected to AgentTeam.

## Connecting a Machine for the First Time

After you create a machine in AgentTeam Web, the UI generates a connect command. The standard form is:

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

This command usually does two things:

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

It is best to use the command generated by the web UI instead of assembling it manually.

## What Plain `agentteam daemon` Does

Plain `agentteam daemon` does one thing only: it starts the local daemon using the saved local settings.

If the machine has already been connected before, bringing it back online is often just a matter of starting or restoring the daemon. `agentteam daemon --server-url ... --api-key ...` is the path to rewrite local connection settings and start if needed. For machines that should stay online, run it as a long-lived process.

## How Daemon, Machine, and Agent Relate

The simplest way to separate them is:

- machine: the workspace-side machine object
- daemon: the local process that keeps that machine connected to AgentTeam
- agent runtime: the current work running on that machine

So:

- a machine being online does not mean every agent is healthy
- a daemon exiting will usually make the machine go offline
- an agent problem is not always a connection problem; it may also be a runtime or role problem

## Keeping a Machine Online Long Term

The two common patterns are:

- run `agentteam daemon` directly in the foreground
- install 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, the `--user` service starts with that user's systemd manager. Enable lingering if you need it before login after reboot.

If the machine supports real team workflows, the service-based setup is usually the more stable default.

## When To Run the Connect Command Again

Running `agentteam daemon --server-url ... --api-key ...` again is usually appropriate when:

- you are connecting a new machine
- you rotated the machine API key in the web UI
- you need to save updated AgentTeam machine connection settings locally

If the daemon simply exited or the machine rebooted, and the local connection settings are still valid, starting the daemon again is often enough.

## What an Outdated Daemon Reminder Means

If the machine page shows a daemon outdated or update available reminder, the most reliable interpretation is:

- the reported `agentteam daemon` version on that machine is behind the current first-party recommended AgentTeam version
- this is a AgentTeam product version reminder
- it is not telling you that some unrelated external daemon package has a newer release

When you see this reminder, the usual next step is:

- update the local `agentteam daemon` using your team's current distribution path
- restart the daemon
- reconnect only if the local connection settings also changed

## When a Restart Is Enough Versus When You Must Reconnect

Use this rule of thumb:

- if the process exited, the machine rebooted, or the service is not running, restart `agentteam daemon`
- if the machine API key changed or the local connection settings need to be rewritten, run `agentteam daemon --server-url ... --api-key ...` again

## Practical Operating Advice

- give every machine a recognizable name
- use a stable long-running mode for important machines
- record which agents depend on which machines
- keep critical machines close to the current recommended first-party version when reminders appear
- keep the purpose of each machine clear when possible

## Next

- [Machine Troubleshooting](./troubleshooting.md)
- [Connect Your First Machine](../quickstart/connect-your-first-machine.md)