SSH - Gravix Layer

Enable SSH

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

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()

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();

gravixlayer runtime ssh enable "$RT" --output json | jq .

gravixlayer runtime ssh enable "$RT" --output json \
  | jq -r '.private_key' > "$HOME/.gravixlayer-$RT.pem"
chmod 600 "$HOME/.gravixlayer-$RT.pem"

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 .

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

Store private keys securely and set file permissions to 600.

Disable SSH

POST /v1/agents/runtime/{runtime_id}/ssh/disable

from gravixlayer import GravixLayer

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

sandbox.enable_ssh()

# Check status
status = sandbox.ssh_status()
print(status.enabled)  # True

# Disable SSH
sandbox.disable_ssh()

# Verify
status = sandbox.ssh_status()
print(status.enabled)  # False

sandbox.kill()

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"

await sandbox.enableSsh();

const enabled = await sandbox.sshStatus();
console.log(enabled.enabled); // true

await sandbox.disableSsh();

const disabled = await sandbox.sshStatus();
console.log(disabled.enabled); // false

await sandbox.kill();

gravixlayer runtime ssh enable "$RT"
gravixlayer runtime ssh status "$RT" --output json | jq .
gravixlayer runtime ssh disable "$RT"
gravixlayer runtime ssh status "$RT" --output json | jq .

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 .

curl -sS "https://api.gravixlayer.ai/v1/agents/runtime/$RT/ssh/status" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" | jq .

curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/ssh/disable" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq .

curl -sS "https://api.gravixlayer.ai/v1/agents/runtime/$RT/ssh/status" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" | jq .

Disable SSH as soon as interactive access is no longer needed.

Key Rotation

Rotate keys when credentials may have been exposed, or as part of regular security policy. POST /v1/agents/runtime/{runtime_id}/ssh/enable?regenerate_keys=true

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"

initial = sandbox.enable_ssh()
print("Initial connect:", initial.connect_cmd)

rotated = sandbox.enable_ssh(regenerate_keys=True)
print("New connect:", rotated.connect_cmd)

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

sandbox.kill()

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 initial = await sandbox.enableSsh();
console.log('Initial connect:', initial.connectCmd);

const rotated = await sandbox.enableSsh({ regenerateKeys: true });
console.log('New connect:', rotated.connectCmd);

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

await sandbox.kill();

gravixlayer runtime ssh enable "$RT" --output json | jq -r '.connect_cmd'

gravixlayer runtime ssh enable "$RT" --regenerate-keys --output json | jq .

gravixlayer runtime ssh enable "$RT" --regenerate-keys --output json \
  | jq -r '.private_key' > "$HOME/.gravixlayer-$RT.pem"
chmod 600 "$HOME/.gravixlayer-$RT.pem"

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 .

curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/ssh/enable?regenerate_keys=true" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq .

Recommended Flow

Call enable_ssh with regenerate_keys=True (CLI: --regenerate-keys).
Save the new private key securely (permissions 600).
Remove old local key files.
Verify access using the new connect_cmd.