Skip to content

nanocoai/nanoclaw / .claude/skills/add-iron-proxy

add-iron-proxy

Flagged

Install or refresh Iron Proxy and its official Iron Control web console for NanoClaw. Use when selecting the Iron gateway, adding its management UI, configuring credentials and grants, or restoring the proxy, approval bridge, and agent guidance.

FileKindSize
REMOVE.mdmarkdown1.7 KB
SKILL.mdskill md18.4 KB
assets/entrypoint.shscript300 B
assets/managed-proxy.Dockerfileother1.0 KB
conformance/credential-scope-cases.goscript3.0 KB
conformance/credential-scope-cases.jsonconfig28.8 KB
evals/evals.jsonconfig983 B
front-proxy/go.modmanifest443 B
front-proxy/go.summanifest3.2 KB
front-proxy/main.goscript22.6 KB
front-proxy/security_test.goscript29.8 KB
gateway.jsonconfig128 B
payload/src/gateway-providers/iron-proxy-allowlist.tsscript2.9 KB
payload/src/gateway-providers/iron-proxy-approval.test.tsscript14.4 KB
payload/src/gateway-providers/iron-proxy-approval.tsscript12.2 KB
payload/src/gateway-providers/iron-proxy-credential-scope.test.tsscript23.6 KB
payload/src/gateway-providers/iron-proxy-credential-scope.tsscript14.1 KB
payload/src/gateway-providers/iron-proxy-local-model.test.tsscript2.3 KB
payload/src/gateway-providers/iron-proxy-local-model.tsscript1.8 KB
payload/src/gateway-providers/iron-proxy-transform.protoother1.4 KB
payload/src/gateway-providers/iron-proxy.test.tsscript16.5 KB
payload/src/gateway-providers/iron-proxy.tsscript21.5 KB
references/control-plane.mdmarkdown4.8 KB
scripts/allowed-hosts.test.tsscript4.0 KB
scripts/auth-resume.test.tsscript6.2 KB
scripts/auth.test.tsscript2.4 KB
scripts/auth.tsscript7.9 KB
scripts/build-managed-proxy.tsscript4.8 KB
scripts/capture-claude-token.shscript963 B
scripts/control-preflight.tsscript3.8 KB
scripts/control.test.tsscript4.5 KB
scripts/control.tsscript11.7 KB
scripts/credential-isolation.test.tsscript5.6 KB
scripts/credential-isolation.tsscript3.9 KB
scripts/credential-store.test.tsscript9.1 KB
scripts/credential-store.tsscript7.0 KB
scripts/detect.test.tsscript1.6 KB
scripts/detect.tsscript1.4 KB
scripts/install-claude.shexecutablescript1.8 KB
scripts/install-command.test.tsscript5.2 KB
scripts/install-command.tsscript4.8 KB
scripts/local-model.test.tsscript2.7 KB
scripts/provider-credentials.test.tsscript18.3 KB
scripts/provider-credentials.tsscript20.1 KB
scripts/setup.test.tsscript7.9 KB
scripts/setup.tsscript17.1 KB
versions.jsonconfig747 B

scripts/setup.ts

View on GitHub
import { getProviderModelEndpoint } from '../../../../src/provider-contracts/index.js';
import { execFileSync } from 'node:child_process';
import { randomBytes } from 'node:crypto';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';

import { getInstallSlug } from '../../../../src/install-slug.js';
import { GATEWAY_ROLE, LABELS } from '../../../../src/drivers/types.js';
import { upsertEnvVar } from '../../../../setup/set-env.js';
import { installStep, installCommand, InstallCommandFailure } from './install-command.js';
import { buildManagedProxy, hasFrontProxy } from './build-managed-proxy.js';
import { controlPaths, installControl, removeControl, storeModelCredential } from './control.js';
import { checkControlEngine } from './control-preflight.js';
import { readAllowedHostsFile, validateAllowedHost } from '../payload/src/gateway-providers/iron-proxy-allowlist.js';

const pins = JSON.parse(
  fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'versions.json'), 'utf8'),
) as Record<string, string>;
let IMAGE = '';

function readProjectEnv(projectRoot: string): Record<string, string> {
  const file = path.join(projectRoot, '.env');
  if (!fs.existsSync(file)) return {};
  return Object.fromEntries(
    fs
      .readFileSync(file, 'utf8')
      .split('\n')
      .map((line) => line.trim())
      .filter((line) => line && !line.startsWith('#') && line.includes('='))
      .map((line) => [line.slice(0, line.indexOf('=')), line.slice(line.indexOf('=') + 1)]),
  );
}

export function statePaths(projectRoot = process.cwd()) {
  const env = readProjectEnv(projectRoot);
  const materialRoot =
    process.env.NANOCLAW_SESSION_MATERIAL_ROOT ||
    env.NANOCLAW_SESSION_MATERIAL_ROOT ||
    path.join(projectRoot, 'data', 'session-materials');
  const root = path.join(materialRoot, 'iron-proxy');
  const shared = path.join(root, 'shared');
  const approvalDir = path.join(root, 'approval');
  return {
    materialRoot,
    root,
    shared,
    approvalDir,
    approvalSocket: path.join(os.tmpdir(), `nanoclaw-iron-socket-${getInstallSlug(projectRoot)}`, 'approval.sock'),
    caCert: path.join(shared, 'ca.crt'),
    caKey: path.join(shared, 'ca.key'),
    secretFile: path.join(shared, 'upstream-secret'),
    configFile: path.join(shared, 'config.yaml'),
    frontConfigFile: path.join(shared, 'front.json'),
    identityKey: path.join(shared, 'workload-identity.key'),
    allowedHosts: path.join(shared, 'allowed-hosts.json'),
    agentCaCert: path.join(projectRoot, 'data', 'gateway-trust', 'iron-proxy', 'ca.crt'),
    containerName: `nanoclaw-iron-proxy-${getInstallSlug(projectRoot)}`,
  };
}

/** A redirect fails: the port it points to stays closed to the agent. */
export function checkModelList(response: string, port: number): void {
  const split = response.indexOf('\r\n\r\n');
  const status = /^HTTP\/1\.[01] (\d{3})/.exec(response)?.[1];
  let body: any;
  try {
    body = split >= 0 ? JSON.parse(response.slice(split + 4)) : undefined;
  } catch {
    body = undefined;
  }
  if (status !== '200' || !body || !Array.isArray(body.data) || body.data.some((m: any) => typeof m?.id !== 'string'))
    throw new Error(
      `Port ${port} on this machine did not answer GET /v1/models with an OpenAI-style model list; it will not be reachable over plain HTTP.`,
    );
}

// Plain HTTP opens a port on this machine, so gateway ports are refused and the model
// list is fetched the way Iron reaches it.
export async function prepareLocalModel(origin: string, projectRoot: string): Promise<void> {
  const port = Number(origin.slice(origin.lastIndexOf(':') + 1));
  const provider = await import('../../../../src/gateway-providers/iron-proxy.js');
  const local = await import('../../../../src/gateway-providers/iron-proxy-local-model.js');
  const settings = provider.readIronProxySettings(process.env, projectRoot);
  if (local.gatewayPorts(settings.approvalPort).includes(port))
    throw new Error(`Port ${port} belongs to a NanoClaw gateway, not a model server.`);
  const image = readProjectEnv(projectRoot).NANOCLAW_IRON_PROXY_IMAGE;
  if (!image) throw new Error('Install Iron Proxy before configuring a local model.');
  let response = '';
  try {
    response = await docker(
      [
        'run',
        '--rm',
        ...(settings.managed ? ['--network', controlPaths(projectRoot).network] : []),
        ...centralHostGatewayArgs(),
        '--entrypoint',
        'sh',
        image,
        '-c',
        // Hold the request side open: BusyBox nc half-closes when stdin ends, and async
        // servers (Uvicorn) then drop the reply. nc exits when the hold ends.
        '{ printf "GET /v1/models HTTP/1.0\\r\\nHost: %s\\r\\nAccept: application/json\\r\\n\\r\\n" "$1"; sleep 5; } | nc -w 5 "$2" "$3"',
        'probe',
        origin,
        local.LOCAL_MODEL_HOST,
        String(port),
      ],
      true,
    );
  } catch (error) {
    if (error instanceof InstallCommandFailure && error.interrupted) throw error;
  }
  checkModelList(response, port);
}

export function readAllowedHosts(projectRoot: string): string[] {
  return readAllowedHostsFile(statePaths(projectRoot).allowedHosts);
}

function writeAllowedHosts(hosts: readonly string[], projectRoot: string): void {
  const file = statePaths(projectRoot).allowedHosts;
  fs.writeFileSync(file, `${JSON.stringify([...new Set(hosts.map(validateAllowedHost))].sort(), null, 2)}\n`, {
    mode: 0o600,
  });
  fs.chmodSync(file, 0o600);
}

async function docker(args: string[], stdout = false): Promise<string> {
  return installCommand('docker', args, {
    label: `Iron Proxy: Docker ${args[0]}`,
    timeoutMs: 180_000,
    capture: stdout,
    failureHint: 'Check Docker and access to the pinned image, then retry.',
  });
}

async function ensureCA(projectRoot: string): Promise<void> {
  const paths = statePaths(projectRoot);
  const hasCert = fs.existsSync(paths.caCert);
  const hasKey = fs.existsSync(paths.caKey);
  if (hasCert !== hasKey) throw new Error(`Iron Proxy CA is incomplete under ${paths.shared}`);
  if (!hasCert) {
    const uid = process.getuid?.();
    const gid = process.getgid?.();
    await docker([
      'run',
      '--rm',
      ...(uid == null ? [] : ['--user', `${uid}:${gid ?? uid}`]),
      '-v',
      `${paths.shared}:/out`,
      IMAGE,
      'generate-ca',
      '-outdir',
      '/out',
      '-name',
      `NanoClaw Iron Proxy ${getInstallSlug(projectRoot)}`,
      '-expiry-hours',
      '87600',
    ]);
  }
  fs.chmodSync(paths.caCert, 0o644);
  fs.chmodSync(paths.caKey, 0o600);
  fs.mkdirSync(path.dirname(paths.agentCaCert), { recursive: true });
  fs.copyFileSync(paths.caCert, paths.agentCaCert);
  fs.chmodSync(paths.agentCaCert, 0o644);
}

function ensureIdentityKey(projectRoot: string): void {
  const file = statePaths(projectRoot).identityKey;
  if (!fs.existsSync(file)) fs.writeFileSync(file, randomBytes(32), { mode: 0o600 });
  if (fs.statSync(file).size < 32) throw new Error(`Iron Proxy identity key is invalid: ${file}`);
  fs.chmodSync(file, 0o600);
}

export function centralHostGatewayArgs(platform = process.platform): string[] {
  return platform === 'linux' ? ['--add-host', 'host.docker.internal:host-gateway'] : [];
}

export function centralInstallLabel(projectRoot = process.cwd()): string {
  return `nanoclaw-install=${getInstallSlug(projectRoot)}`;
}

async function startCentralProxy(projectRoot: string): Promise<void> {
  IMAGE = readProjectEnv(projectRoot).NANOCLAW_IRON_PROXY_IMAGE || IMAGE;
  const managed = !!readProjectEnv(projectRoot).NANOCLAW_IRON_CONTROL_URL;
  const paths = statePaths(projectRoot);
  const uid = process.getuid?.();
  const gid = process.getgid?.();
  try {
    await docker(['rm', '-f', paths.containerName]);
  } catch (error) {
    if (error instanceof InstallCommandFailure && error.interrupted) throw error;
    // First install has no previous provider-owned container.
  }
  await docker([
    'run',
    '-d',
    '--name',
    paths.containerName,
    ...(managed
      ? ['--network', controlPaths(projectRoot).network, '--env-file', controlPaths(projectRoot).proxyEnvironment]
      : []),
    '--label',
    centralInstallLabel(projectRoot),
    '--label',
    `${LABELS.role}=${GATEWAY_ROLE}`,
    ...(uid == null ? [] : ['--user', `${uid}:${gid ?? uid}`]),
    ...centralHostGatewayArgs(),
    '--restart',
    'unless-stopped',
    '--read-only',
    '--cap-drop',
    'ALL',
    '--security-opt',
    'no-new-privileges',
    '--pids-limit',
    '256',
    '--tmpfs',
    '/tmp:rw,noexec,nosuid,size=64m',
    '-v',
    `${paths.configFile}:/etc/iron-proxy/config.yaml:ro`,
    '-v',
    `${paths.frontConfigFile}:/etc/iron-proxy/front.json:ro`,
    '-v',
    `${paths.caCert}:/etc/iron-proxy/ca.crt:ro`,
    '-v',
    `${paths.caKey}:/etc/iron-proxy/ca.key:ro`,
    ...(managed ? [] : ['-v', `${paths.secretFile}:/run/secrets/upstream:ro`]),
    '-v',
    `${paths.identityKey}:/run/secrets/workload-identity-key:ro`,
    '-v',
    `${paths.approvalDir}:/run/nanoclaw-gateway:ro`,
    ...(process.platform === 'darwin'
      ? [
          '-v',
          `${path.join(paths.shared, 'approval-client.crt')}:/run/secrets/approval-client.crt:ro`,
          '-v',
          `${path.join(paths.shared, 'approval-client.key')}:/run/secrets/approval-client.key:ro`,
        ]
      : []),
    IMAGE,
    '-config',
    '/etc/iron-proxy/config.yaml',
  ]);
}

export async function configureCredential(
  credential: { secret: string; authEnv: string; modelHost: string; baseUrl?: string },
  projectRoot = process.cwd(),
): Promise<void> {
  if (!['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN'].includes(credential.authEnv)) {
    throw new Error(`Unsupported Iron Proxy auth env: ${credential.authEnv}`);
  }
  if (!credential.secret || /[\r\n]/.test(credential.secret)) throw new Error('Credential must be one non-empty line');
  const paths = statePaths(projectRoot);
  if (readProjectEnv(projectRoot).NANOCLAW_IRON_CONTROL_URL) {
    await storeModelCredential(credential.secret, credential.modelHost, projectRoot, credential.authEnv);
  } else {
    fs.writeFileSync(paths.secretFile, credential.secret, { mode: 0o600 });
    fs.chmodSync(paths.secretFile, 0o600);
  }
  upsertEnvVar('NANOCLAW_IRON_PROXY_AUTH_ENV', credential.authEnv, projectRoot);
  upsertEnvVar('NANOCLAW_IRON_PROXY_MODEL_HOST', validateAllowedHost(credential.modelHost), projectRoot);
  if (credential.baseUrl) upsertEnvVar('ANTHROPIC_BASE_URL', credential.baseUrl, projectRoot);
}

export async function run(args: string[], projectRoot = process.cwd()): Promise<void> {
  if (args.includes('--remove')) {
    try {
      await docker(['rm', '-f', statePaths(projectRoot).containerName]);
    } catch (error) {
      if (error instanceof InstallCommandFailure && error.interrupted) throw error;
      // Already absent is the desired removal state.
    }
    await removeControl(projectRoot);
    return;
  }
  const managed = args.includes('--with-control') || !!readProjectEnv(projectRoot).NANOCLAW_IRON_CONTROL_URL;
  const localIndex = args.indexOf('--local-image');
  if (managed || localIndex < 0) {
    // An engine that cannot run the console stops here, before the Iron
    // Proxy build spends minutes.
    if (managed) await checkControlEngine();
    IMAGE = await buildManagedProxy();
    if (managed) await installControl(projectRoot);
    upsertEnvVar('NANOCLAW_IRON_PROXY_IMAGE', IMAGE, projectRoot);
  }
  const localImage = localIndex >= 0 ? args[localIndex + 1] : readProjectEnv(projectRoot).NANOCLAW_IRON_PROXY_IMAGE;
  if (localImage && (localIndex >= 0 || localImage.startsWith('sha256:'))) {
    const inspected = JSON.parse(await docker(['image', 'inspect', localImage], true))[0];
    if (inspected.Config.Labels?.['org.opencontainers.image.revision'] !== pins['iron-proxy-commit']) {
      throw new Error('Local image was not built from the pinned Iron Proxy commit');
    }
    if (!hasFrontProxy(inspected)) throw new Error('Iron Proxy requires the bundled NanoClaw approval front proxy');
    IMAGE = inspected.Id;
  }
  if (
    !/^sha256:[0-9a-f]{64}$/.test(IMAGE) &&
    !/^ghcr\.io\/[a-z0-9._/-]+(?::[a-z0-9._-]+)?@sha256:[0-9a-f]{64}$/.test(IMAGE)
  ) {
    throw new Error('Iron Proxy skill does not contain an exact image digest');
  }
  const paths = statePaths(projectRoot);
  fs.mkdirSync(paths.shared, { recursive: true, mode: 0o700 });
  fs.mkdirSync(paths.approvalDir, { recursive: true, mode: 0o700 });
  fs.chmodSync(paths.shared, 0o700);
  fs.chmodSync(paths.approvalDir, 0o700);
  const allowIndex = args.indexOf('--allow-host');
  const allowed = readAllowedHosts(projectRoot);
  if (allowIndex >= 0) {
    if (!args[allowIndex + 1]) throw new Error('--allow-host requires a hostname or *.domain');
    allowed.push(validateAllowedHost(args[allowIndex + 1]));
  }
  writeAllowedHosts(allowed, projectRoot);
  if (!IMAGE.startsWith('sha256:')) await docker(['pull', IMAGE]);
  await ensureCA(projectRoot);
  ensureIdentityKey(projectRoot);
  if (process.platform === 'darwin') {
    const port =
      readProjectEnv(projectRoot).NANOCLAW_IRON_PROXY_APPROVAL_PORT ||
      String(19000 + (parseInt(getInstallSlug(projectRoot), 16) % 10000));
    upsertEnvVar('NANOCLAW_IRON_PROXY_APPROVAL_PORT', port, projectRoot);
    for (const name of ['server', 'client']) {
      const base = path.join(paths.shared, `approval-${name}`);
      if (fs.existsSync(`${base}.crt`) && fs.existsSync(`${base}.key`)) continue;
      const extensions = `${base}.ext`;
      fs.writeFileSync(
        extensions,
        `basicConstraints=CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=${name === 'server' ? 'serverAuth' : 'clientAuth'}\nsubjectAltName=DNS:host.docker.internal,IP:127.0.0.1\n`,
      );
      execFileSync(
        'openssl',
        [
          'req',
          '-new',
          '-newkey',
          'rsa:2048',
          '-nodes',
          '-keyout',
          `${base}.key`,
          '-out',
          `${base}.csr`,
          '-subj',
          `/CN=NanoClaw Approval ${name}`,
        ],
        { stdio: 'ignore', timeout: 30_000 },
      );
      fs.chmodSync(`${base}.key`, 0o600);
      execFileSync(
        'openssl',
        [
          'x509',
          '-req',
          '-in',
          `${base}.csr`,
          '-CA',
          paths.caCert,
          '-CAkey',
          paths.caKey,
          '-set_serial',
          name === 'server' ? '11' : '12',
          '-out',
          `${base}.crt`,
          '-days',
          '365',
          '-extfile',
          extensions,
        ],
        { stdio: 'ignore', timeout: 30_000 },
      );
      fs.rmSync(`${base}.csr`);
      fs.rmSync(extensions);
    }
  }
  if (!fs.existsSync(paths.secretFile)) fs.writeFileSync(paths.secretFile, 'not-configured', { mode: 0o600 });
  fs.chmodSync(paths.secretFile, 0o600);

  upsertEnvVar('NANOCLAW_IRON_PROXY_IMAGE', IMAGE, projectRoot);
  upsertEnvVar('NANOCLAW_IRON_PROXY_CA_CERT', paths.caCert, projectRoot);
  upsertEnvVar('NANOCLAW_IRON_PROXY_CA_KEY', paths.caKey, projectRoot);
  upsertEnvVar('NANOCLAW_IRON_PROXY_SECRET_FILE', paths.secretFile, projectRoot);
  upsertEnvVar('NANOCLAW_IRON_PROXY_CONFIG_FILE', paths.configFile, projectRoot);
  upsertEnvVar('NANOCLAW_IRON_PROXY_IDENTITY_KEY', paths.identityKey, projectRoot);
  upsertEnvVar('NANOCLAW_IRON_PROXY_CONTAINER', paths.containerName, projectRoot);
  upsertEnvVar('NANOCLAW_IRON_PROXY_APPROVAL_SOCKET', paths.approvalSocket, projectRoot);
  upsertEnvVar('NANOCLAW_IRON_PROXY_ALLOWED_HOSTS', paths.allowedHosts, projectRoot);
  upsertEnvVar('NANOCLAW_EGRESS_LOCKDOWN', 'true', projectRoot);
  if (!readProjectEnv(projectRoot).NANOCLAW_EGRESS_NETWORK) {
    upsertEnvVar('NANOCLAW_EGRESS_NETWORK', `nanoclaw-egress-${getInstallSlug(projectRoot)}`, projectRoot);
  }
  if (!readProjectEnv(projectRoot).NANOCLAW_IRON_PROXY_AUTH_ENV) {
    upsertEnvVar('NANOCLAW_IRON_PROXY_AUTH_ENV', 'ANTHROPIC_API_KEY', projectRoot);
  }
  if (!readProjectEnv(projectRoot).NANOCLAW_IRON_PROXY_MODEL_HOST) {
    upsertEnvVar(
      'NANOCLAW_IRON_PROXY_MODEL_HOST',
      new URL(getProviderModelEndpoint('claude', 'api')).hostname,
      projectRoot,
    );
  }
  const provider = await import('../../../../src/gateway-providers/iron-proxy.js');
  const settings = provider.readIronProxySettings(process.env, projectRoot);
  if (managed) {
    const existingSecret = fs.readFileSync(paths.secretFile, 'utf8').trim();
    if (existingSecret && existingSecret !== 'not-configured') {
      await storeModelCredential(existingSecret, settings.modelHost, projectRoot, settings.authEnv);
      fs.writeFileSync(paths.secretFile, 'not-configured', { mode: 0o600 });
    }
  }
  fs.writeFileSync(paths.configFile, provider.ironProxyConfig(settings), { mode: 0o600 });
  fs.chmodSync(paths.configFile, 0o600);
  fs.writeFileSync(paths.frontConfigFile, provider.ironFrontConfig(settings), { mode: 0o600 });
  fs.chmodSync(paths.frontConfigFile, 0o600);
  await startCentralProxy(projectRoot);
  console.log(`Central Iron Proxy ${pins['iron-proxy-commit']} is ready.`);
}

if (
  process.argv[1] &&
  fs.existsSync(process.argv[1]) &&
  import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href
) {
  void installStep(() => run(process.argv.slice(2))).then((ok) => {
    if (!ok) process.exitCode = 1;
  });
}
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall