# SSH access to a machine Let an agent SSH into a machine you name, such as a test VM, without copying a key onto it. The agent holds no standing SSH key. While you allow it, the agent gets a certificate from the swarm's SSH certificate authority (CA) that lasts an hour. The machine trusts the CA, so it needs no list of keys. Two things have to be true before an agent gets in: 1. **You switch SSH on for that agent**, in the swarm UI. 2. **The machine trusts the CA** and lists the agent. Every agent already has an SSH client, a key it makes in memory, and a certificate unit. The switch alone decides whether the swarm signs. ## 1. Switch it on for an agent Open the agent's card in the swarm UI and find the **ssh** row. Select it and tick **allow the agent to get SSH certificates**. The default is off. The agent has a certificate within about 25 minutes of the change. Untick the box to stop new certificates. The row also shows the three forms of the target setup below, already filled in with the swarm's CA key and the agent's name. The agent then runs `ssh user@host`, with no other setup. It offers its certificate and nothing else. **Host keys use trust on first use.** The agent accepts the key a machine shows on the first connection, keeps it in its state directory (so it survives restarts), and refuses a changed key afterwards. A swapped machine on the first contact would go unnoticed. The row's explainer says so. This doesn't open the network. If you set the hive's `egress.forward` to `reject`, the hive refuses the agent's direct connection to the machine's port until a separate allowance exists; the default `log` lets it through. See [the network page](../../4-implementation/networking/network.md). ## 2. Make a machine trust the CA Open **on the target** in the same row. It shows the swarm's CA public key, a public value, and the agent's name, in three forms. Replace `` with the account the agent logs in as. The target never contacts the swarm. - **NixOS:** the CA key in `services.openssh.settings.TrustedUserCAKeys` and `users.users..openssh.authorizedPrincipals = [ "" ];`. The same as one module: import `hyperhive.nixosModules.agent-ssh-target` and set `services.hyperhive.agentSshTarget` (`enable`, `caPublicKey`, `principals.`). - **home-manager:** `home.file.".ssh/authorized_keys".text` holding one `cert-authority` line. - **plain ssh:** one line in the account's `~/.ssh/authorized_keys`: ``` cert-authority,principals="" ssh-ed25519 AAAA… ``` This works on any machine without a change to its sshd config. To read the CA key outside the UI, run this on the swarm's store host: ```bash bao read -field=public_key ssh-agents/config/ca ``` ## What an agent can and can't do - It can only get a certificate for **its own name**. The store signs for the name its identity carries, so atlas can't obtain one that says maia. - The certificate lasts an hour, and the agent signs a new one every 20 minutes. The key lives in the agent's `/run` (memory) and never reaches disk. A new container start makes a new key. - It signs ed25519 user keys only, and the certificate allows a terminal (`permit-pty`) and nothing else. ## Revoking access - **One agent from one machine:** remove its principal (the `authorizedPrincipals` entry, or the `cert-authority` line) and deploy the machine. The next login attempt fails. - **One agent from every machine:** untick the switch. The swarm stops signing for it within five minutes; an agent already signed in can still sign for up to an hour. Destroying the agent cuts its store identity off within minutes. Either way a certificate already signed stays valid until it expires, at most three hours, so removing the principal on a machine is what cuts it off there at once. - **The CA itself:** if the CA key changes, every machine needs the new public key. Nothing replaces the CA by itself. For the bao paths, field names and units, see [the SSH CA implementation page](../../4-implementation/swarm/ssh-ca.md).