# 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. It asks the swarm's secret store for a certificate that lasts an hour, and the machine trusts the swarm's SSH certificate authority (CA) instead of a list of keys. Nothing changes until you do both of these: 1. Switch SSH on for the agent and name the machines it may reach. 2. Make each machine trust the CA and list the agents allowed in. ## 1. Switch it on for an agent In the agent's config: ```nix services.hyperhive.agent.ssh = { enable = true; hosts.testvm = { hostName = "10.0.0.7"; user = "test"; port = 22; # the default hostKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…"; }; }; ``` `hostKey` is the machine's own host public key, the one line in `/etc/ssh/ssh_host_ed25519_key.pub` on it. The agent pins it: it refuses a machine that presents any other key, and never trusts a key on first sight. The agent then runs `ssh testvm` with no other flag. The agent's SSH client offers its certificate and nothing else. The option needs the agent to have a store identity, the same as for its other store credentials. 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 On the swarm's store host, read the CA's public key: ```bash bao read -field=public_key ssh-agents/config/ca ``` The store also serves the same key without a token at `/v1/ssh-agents/public_key`. The key is public and you set it once. Then import the module on the machine, which can be any NixOS machine, and not only a hive host: ```nix { imports = [ hyperhive.nixosModules.agent-ssh-target ]; services.hyperhive.agentSshTarget = { enable = true; caPublicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…"; principals.test = [ "atlas" "maia" ]; }; } ``` `principals.` lists the agents that may log in as that local account. The account has to exist. An account with no entry accepts no certificate. The module writes no `authorized_keys`. ## 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 name from that user's `principals` and deploy the machine. The next login attempt fails. - **One agent from every machine:** delete its cert-auth role `hive-agent-` in the store. It can no longer log in to the store, so nothing signs for it, and its last certificate lapses within three hours. - **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).