> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Add an SSH connection
> Save encrypted password or private-key authentication for a Linux host. Does not connect yet. Explicit host-access consent and a non-secret idempotency_key are required. Same key/body replays for 24 hours, including after credential rotation. Changed bodies, expired keys and deleted connections conflict. Keep credentials in a caller-side secret manager, never prompts or command history. REST only.
## Server setup requirements
Reason's hosted connector initiates SSH from Reason's cloud, not from your browser or computer. Configure the server before saving a connection:
1. Use a Linux server with an x64 or arm64 CPU. macOS and Windows are not supported by this automatic installation flow. SSH devices run headlessly; they do not provide desktop streaming or interactive desktop control.
2. Provide a public hostname or IP address and an SSH port reachable from Reason's cloud. Private LAN, localhost, and Tailscale-only addresses are not supported. A successful SSH connection from your own computer does not prove cloud reachability. Configure the server's firewall and any upstream network rules according to your organization's security policy; do not disable the firewall.
3. Enable SSH and authorize the supplied SSH user with a password or private key. Prefer a dedicated, least-privileged account and key. The account needs a private, writable home directory, disk space for the worker, and permission to read, write, and execute within its workspace. Root access is not required.
4. Allow outbound HTTPS for the CLI download and the worker's connection to Reason. The host needs bash, curl, getent, stat, readlink, and timeout. With systemd, a non-root user needs lingering enabled by the administrator. Without systemd, use Reconnect after the host restarts or the worker stops.
5. Save the connection, then connect to probe the SSH host key. Compare the fingerprint with a trusted source before choosing Trust & install. Reason installs and enrolls the worker only after that verification.
If setup fails, inspect the connection's error_code: ssh_host_blocked means the address is not permitted; ssh_dns_failed means name resolution failed; ssh_authentication_failed means the credentials were rejected; ssh_platform_unsupported means the operating system or architecture is unsupported. A connected setup receipt is not proof that the Device remains online; check its current Device status.
Scope: `ssh:write`
## OpenAPI
````yaml /openapi.json post /v3/organizations/{orgId}/ssh-connections
openapi: 3.1.0
info:
title: Reason Machines API
version: 3.0.0
description: >-
The Reason HTTP API. Drive cloud software-engineering agents: open sessions
against your repositories, stream their work, and manage the secrets,
knowledge, skills, and automations they run with.
Authenticate with a Reason API key sent as a bearer token. New keys use
`reason_`; legacy `ara_` keys remain accepted. Every resource is scoped to
an organization; resolve your `org_id` once with `GET /v3/self`.
servers:
- url: https://api.reasonmachines.ai
security:
- araApiKey: []
tags:
- name: Devices
description: >-
Owned Mac and headless Device identity, bounded enrollment and root
grants.
- name: Account
description: Verify a key and resolve the organization it belongs to.
- name: Projects
description: >-
Discover existing workspace projects to target when creating and listing
sessions.
- name: Sessions
description: >-
A session is one run of an agent against a repository: it reproduces the
task, writes the code, verifies it, and opens a pull request or merge
request.
- name: Secrets
description: >-
Encrypted credentials injected into the agent's sandbox. Write-only:
values can be set but never read back.
- name: Knowledge
description: Durable notes the agent consults while it works.
- name: Memory
description: >-
Editable repository notes that are projected into native memory; generated
memory remains read-only.
- name: Skills
description: >-
Reusable instruction bundles Reason selects semantically from their
descriptions for matching agent tasks.
- name: Automations
description: Recurring or one-time triggers that open sessions on a timetable.
- name: Change Request Reviews
description: >-
Automated senior-engineer reviews posted on pull requests and merge
requests.
- name: Repositories
description: Connected repositories, their indexing state, and generated wikis.
- name: Git Connections
description: Linked source-control accounts and the repositories they expose.
- name: Consumption
description: 'Billing-aligned usage: daily consumption and billing cycles.'
- name: Metrics
description: Aggregate analytics over sessions, change requests, and usage.
- name: Audit Logs
description: An append-only record of changes made within the organization.
- name: Organizations
description: The top-level tenant. Create, read, update, and delete organizations.
- name: Members
description: People in an organization and their pending invites.
- name: Service Users
description: Machine principals that own API keys for headless access.
- name: Roles
description: Role assignments that govern what each member can do.
- name: Attachments
description: >-
Files uploaded to the organization and shared with sessions, downloaded
via short-lived signed URLs.
- name: Guardrails
description: >-
Per-repository automation limits and the violations recorded when a limit
is hit.
- name: MCP Servers
description: >-
Org-level Model Context Protocol servers exposed to the agent. Secret
values are write-only.
- name: Settings
description: 'Organization configuration: namespaced settings and the run tag policy.'
- name: Blueprints
description: >-
Read-only declarative manifests of an organization's agents (identity, run
config, triggers, suite), with credentials redacted.
- name: IP Access List
description: >-
Source-network allow-list that, when enabled, restricts the organization's
API surface to a set of CIDR ranges.
- name: Groups
description: Manually-curated member groups carrying optional per-day resource limits.
- name: Provider Credentials
description: >-
Configure Bring-Your-Own-Key (BYOK) API keys and subscription credentials
for model providers. Secret values are write-only.
paths:
/v3/organizations/{orgId}/ssh-connections:
parameters:
- $ref: '#/components/parameters/orgId'
post:
tags:
- Devices
summary: Add an SSH connection
description: >-
Save encrypted password or private-key authentication for a Linux host.
Does not connect yet. Explicit host-access consent and a non-secret
idempotency_key are required. Same key/body replays for 24 hours,
including after credential rotation. Changed bodies, expired keys and
deleted connections conflict. Keep credentials in a caller-side secret
manager, never prompts or command history. REST only.
## Server setup requirements
Reason's hosted connector initiates SSH from Reason's cloud, not from
your browser or computer. Configure the server before saving a
connection:
1. Use a Linux server with an x64 or arm64 CPU. macOS and Windows are
not supported by this automatic installation flow. SSH devices run
headlessly; they do not provide desktop streaming or interactive desktop
control.
2. Provide a public hostname or IP address and an SSH port reachable
from Reason's cloud. Private LAN, localhost, and Tailscale-only
addresses are not supported. A successful SSH connection from your own
computer does not prove cloud reachability. Configure the server's
firewall and any upstream network rules according to your organization's
security policy; do not disable the firewall.
3. Enable SSH and authorize the supplied SSH user with a password or
private key. Prefer a dedicated, least-privileged account and key. The
account needs a private, writable home directory, disk space for the
worker, and permission to read, write, and execute within its workspace.
Root access is not required.
4. Allow outbound HTTPS for the CLI download and the worker's connection
to Reason. The host needs bash, curl, getent, stat, readlink, and
timeout. With systemd, a non-root user needs lingering enabled by the
administrator. Without systemd, use Reconnect after the host restarts or
the worker stops.
5. Save the connection, then connect to probe the SSH host key. Compare
the fingerprint with a trusted source before choosing Trust & install.
Reason installs and enrolls the worker only after that verification.
If setup fails, inspect the connection's error_code: ssh_host_blocked
means the address is not permitted; ssh_dns_failed means name resolution
failed; ssh_authentication_failed means the credentials were rejected;
ssh_platform_unsupported means the operating system or architecture is
unsupported. A connected setup receipt is not proof that the Device
remains online; check its current Device status.
Scope: `ssh:write`
operationId: createSshConnection
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSshConnection'
example:
name: Build host
host: host.example.com
username: ubuntu
authentication:
type: private_key
private_key:
consent_host_access: true
idempotency_key: save-build-host-001
responses:
'200':
description: Original saved receipt replayed.
content:
application/json:
schema:
$ref: '#/components/schemas/SshConnectionCreated'
'201':
description: Saved connection.
content:
application/json:
schema:
$ref: '#/components/schemas/SshConnectionCreated'
'400':
description: >-
Invalid input; credential values and validation details are never
reflected.
'401':
description: A valid public bearer credential is required.
'403':
description: Required scope or workspace access is missing.
'404':
description: Owned SSH connection not found.
'409':
description: >-
Setup in progress, changed host key, quota, conflicting/expired
idempotency key, or deleted connection.
'413':
description: Request exceeds 48 KiB.
'429':
description: Rate/cooldown limit; respect Retry-After.
'503':
description: >-
Writes, headless admission, encrypted storage, audit or cleanup
unavailable.
security:
- araApiKey:
- ssh:write
components:
parameters:
orgId:
name: orgId
in: path
required: true
description: Organization id or slug. Resolve it with `GET /v3/self`.
schema:
type: string
schemas:
CreateSshConnection:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 160
host:
type: string
minLength: 1
maxLength: 253
pattern: ^[a-zA-Z0-9.:_-]+$
port:
default: 22
type: integer
minimum: 1
maximum: 65535
username:
type: string
minLength: 1
maxLength: 77
description: >-
SSH username, up to 64 characters, or Railway's sbx:: routing selector.
workspace_path:
description: >-
Optional absolute remote workspace path. Omit to use the installer's
private default workspace.
type: string
minLength: 1
maxLength: 1024
authentication:
oneOf:
- type: object
properties:
type:
type: string
const: password
password:
type: string
minLength: 1
maxLength: 4096
writeOnly: true
required:
- type
- password
additionalProperties: false
- type: object
properties:
type:
type: string
const: private_key
private_key:
type: string
minLength: 1
maxLength: 32768
writeOnly: true
passphrase:
writeOnly: true
type: string
maxLength: 4096
required:
- type
- private_key
additionalProperties: false
consent_host_access:
type: boolean
const: true
idempotency_key:
type: string
minLength: 1
maxLength: 160
pattern: ^[A-Za-z0-9._:-]+$
description: >-
Persist one non-secret key per logical request. Retry the identical
body/key for up to 24 hours. Expired or deleted request keys return
409; reconnect intentionally with a fresh key.
required:
- name
- host
- username
- authentication
- consent_host_access
- idempotency_key
additionalProperties: false
SshConnectionCreated:
type: object
properties:
connection:
type: object
properties:
id:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
name:
type: string
host:
type: string
port:
type: integer
username:
type: string
workspace_path:
type:
- string
- 'null'
auth_type:
type: string
enum:
- password
- private_key
host_key_fingerprint:
type:
- string
- 'null'
pending_host_key_fingerprint:
type:
- string
- 'null'
device_id:
type:
- string
- 'null'
status:
type: string
enum:
- saved
- connecting
- awaiting_host_key
- connected
- failed
error_code:
type:
- string
- 'null'
created_at:
type: string
updated_at:
type: string
required:
- id
- name
- host
- port
- username
- workspace_path
- auth_type
- host_key_fingerprint
- pending_host_key_fingerprint
- device_id
- status
- error_code
- created_at
- updated_at
additionalProperties: false
replayed:
type: boolean
required:
- connection
- replayed
additionalProperties: false
securitySchemes:
araApiKey:
type: http
scheme: bearer
bearerFormat: 'reason_ (legacy: ara_)'
description: >-
Your Reason API key from Settings > API. New keys use `reason_`; legacy
`ara_` keys remain accepted. Keys are capability-scoped: run, mcp:read,
mcp:write, secrets:read, secrets:write, sessions:read, sessions:debug,
knowledge:read, memory:read, memory:write, skills:read, skills:write,
repos:read, repos:write, reviews:read, reviews:write, deployment:read,
analytics:read, org:read, org:write, attachments:read,
attachments:write, guardrails:read, guardrails:write, automations:read,
automations:write, agent_auth:read. mcp:write manages MCP server
configuration only; it does not authorize remote MCP-tool execution.
sessions:debug is privileged: it expands diagnostic session events only
for organization owners/admins.
````