Add an SSH connection

Adding a connection is three things: pin the host, seal the key, and declare the capabilities. The console does all of it in one form; the permaura CLI does it in one command; the REST API in a few calls.

1. Pin the host's fingerprint

The connection refuses to connect unless the server presents this exact key, so grab it first:

FP=$(ssh-keyscan -t ed25519 db1.example.com | ssh-keygen -lf - | awk '{print $2}')
echo "$FP"   # SHA256:9Ije0/h/UFCjrsPr+a6o/dPtQhd0p9AbIQOW10Q7wJo

2. Create the connection

Console

Open Access → Connections → Add connection and choose SSH server. The form walks the same three steps:

• Name, Host, Port, Username: the SSH target, pinned server-side.
• Host key fingerprint: paste the SHA256:… value from step 1. ("Skip host key verification" exists for a local dev box; don't use it across an untrusted network.)
• Authenticate with: a private key (paste it or upload the file) or a password. Either is sealed on the gateway and never shown again.
• Allowed commands: one row per exec capability: an action name (restart-app) and its command template (systemctl restart {service}). A {name} placeholder becomes the only thing an agent may fill in.
• File access root: optional; exposes path-scoped sftp.get / sftp.put / sftp.list under that directory.

Save, and the connection appears on the Connections page with its capabilities listed. Nothing is usable until a grant allows it.

permaura CLI

One command creates the connection, seals the key, and grants it to an agent:

permaura connection add-ssh db1 \
  --host db1.example.com --user deploy \
  --host-key-sha256 "$FP" \
  --key-file ~/.ssh/db1_ed25519 \
  --sftp-root /var/data \
  --exec 'uptime:uptime' \
  --exec 'restart:systemctl,restart,{service}' \
  --agent codex-cli

• --exec 'action:program,arg,arg' defines one exec capability. A {name} argument becomes an allow-listed placeholder the agent may fill.
• --sftp-root exposes sftp.get / sftp.put / sftp.list, all scoped under that directory.
• Add --require-approval to gate the exec commands on a human. (Writes and sftp.put are higher-risk and escalate automatically regardless.)
• For a local or dev host with no fingerprint, --insecure skips verification. Do not use it against a host reached over an untrusted network.

REST API

The same thing over REST v1 ($TOKEN is your operator token):

BASE=http://127.0.0.1:7376

# a) the connection: host/user/host-key pinned, capabilities declared
curl -X POST $BASE/v1/connections -H @<(printf 'authorization: Bearer %s\n' "$TOKEN") -H 'content-type: application/json' -d '{
  "id": "db1", "connector": "ssh", "name": "DB box",
  "ssh": {
    "host": "db1.example.com", "port": 22, "user": "deploy",
    "host_key_sha256": "SHA256:9Ije…",
    "sftp_root": "/var/data",
    "exec": [
      { "action": "uptime",  "args_template": ["uptime"] },
      { "action": "restart", "args_template": ["systemctl","restart","{service}"],
        "allowed_placeholders": ["service"], "risk": "high", "requires_approval": true }
    ]
  }
}'

# b) seal the private key (no route returns it on its own; a vault export carries it)
curl -X POST $BASE/v1/connections/db1/credential -H @<(printf 'authorization: Bearer %s\n' "$TOKEN") \
  -H 'content-type: application/json' --data-binary @<(jq -Rs '{value: .}' < ~/.ssh/db1_ed25519)

# c) allow the actions and grant them to an agent
curl -X POST $BASE/v1/policies -H @<(printf 'authorization: Bearer %s\n' "$TOKEN") -H 'content-type: application/json' -d '{
  "connection_id": "db1", "allow": ["uptime","restart","sftp.list","sftp.get"] }'
curl -X POST $BASE/v1/grants -H @<(printf 'authorization: Bearer %s\n' "$TOKEN") -H 'content-type: application/json' -d '{
  "policy_ids": ["<the pol_… id returned above>"], "agents": [{ "agent_id": "codex-cli" }] }'

The -H @<(…) form reads the header from a process substitution, so the token is never one of curl's arguments; it needs bash or zsh, since a POSIX sh does not know <(…).

What you get

The connection now exposes these capabilities (namespaced under its id):

Capability	What it does
db1.uptime	runs uptime on the host
db1.restart	runs systemctl restart <service> (approval-gated)
db1.sftp.list	lists a directory under /var/data
db1.sftp.get	reads a file under /var/data
db1.sftp.put	writes a file under /var/data (higher-risk)

Use it from an agent

Point an MCP client (Claude, ChatGPT, Cursor) at your gateway and the capabilities appear as tools named db1.uptime, db1.sftp.get, and so on. The agent calls them like any other tool:

• db1.uptime with {} returns the real uptime line from the host.
• db1.sftp.get with { "path": "reports/q3.csv" } returns the file's bytes (base64), scoped under the root.
• db1.restart with { "service": "nginx" } returns awaiting approval and waits for you in the console or the Permaura app; it runs only once you approve.

The key is used on the gateway's machine and leaves it only through a vault export, which, once a device is paired, waits for its approval unless you have lowered the approval floor. On a hosted gateway its sealed form is also kept in the worker's encrypted backups. Every call a policy decides on, and every export, lands in the signed audit log.

Notes

• The key you seal must be unencrypted (this build authenticates with no passphrase). Generate a dedicated one with ssh-keygen -t ed25519 -f ~/.ssh/db1_ed25519 -N '' and authorize it on the host.
• Password auth is supported with --password-env VAR (the value is read from that environment variable and sealed, never placed on a command line).
• Check what is configured any time with permaura connection list.