> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravixlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Enable SSH

> Enable SSH access and retrieve connection details for a runtime

`POST /v1/agents/runtime/{runtime_id}/ssh/enable`

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from pathlib import Path

  from gravixlayer import GravixLayer

  client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
  sandbox = client.runtime.create()  # defaults to template="base-small"

  ssh = sandbox.enable_ssh()

  print(ssh.enabled)      # True
  print(ssh.username)     # agent
  print(ssh.port)
  print(ssh.connect_cmd)

  if ssh.private_key:
      key_path = Path.home() / f".gravixlayer-{sandbox.runtime_id}.pem"
      key_path.write_text(ssh.private_key)
      key_path.chmod(0o600)

  sandbox.kill()
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { chmod, writeFile } from 'node:fs/promises';
  import { homedir } from 'node:os';
  import { join } from 'node:path';

  import { GravixLayer } from 'gravixlayer';

  const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
  const sandbox = await client.runtime.create(); // defaults to template="base-small"

  const ssh = await sandbox.enableSsh();

  console.log(ssh.enabled);    // true
  console.log(ssh.username);   // agent
  console.log(ssh.port);
  console.log(ssh.connectCmd);

  if (ssh.privateKey) {
    const keyPath = join(homedir(), `.gravixlayer-${sandbox.runtimeId}.pem`);
    await writeFile(keyPath, ssh.privateKey, { mode: 0o600 });
    await chmod(keyPath, 0o600);
  }

  await sandbox.kill();
  ```

  ```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  gravixlayer runtime ssh enable "$RT" --output json | jq .

  # Save private key (permissions 600):
  gravixlayer runtime ssh enable "$RT" --output json \
    | jq -r '.private_key' > "$HOME/.gravixlayer-$RT.pem"
  chmod 600 "$HOME/.gravixlayer-$RT.pem"
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/ssh/enable" \
    -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{}' | jq .
  ```
</CodeGroup>

## Parameters

| Parameter         | Type    | Required | Description                           |
| ----------------- | ------- | -------- | ------------------------------------- |
| `regenerate_keys` | boolean | No       | Regenerate SSH keys (default `False`) |

## Response

| Field         | Type    | Description             |
| ------------- | ------- | ----------------------- |
| `runtime_id`  | string  | Runtime identifier      |
| `enabled`     | boolean | SSH enabled status      |
| `port`        | integer | SSH port                |
| `username`    | string  | SSH username            |
| `connect_cmd` | string  | Full SSH command        |
| `private_key` | string  | PEM-encoded private key |
| `public_key`  | string  | Public key              |
| `ssh_config`  | string  | SSH config block        |
| `message`     | string  | Status message          |

<Info>
  Store private keys securely and set file permissions to `600`.
</Info>