nanocoai/nanoclaw / .claude/skills/add-iron-proxy
add-iron-proxy
FlaggedInstall 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.
scripts/control.ts
View on GitHubimport { randomBytes } from 'node:crypto';
import fs from 'node:fs';
import { assertCredentialIsolation } from './credential-isolation.js';
import path from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { installCommand } from './install-command.js';
import { stringify as yaml } from 'yaml';
import { GATEWAY_ROLE, LABELS } from '../../../../src/drivers/types.js';
import { getInstallSlug } from '../../../../src/install-slug.js';
import { upsertEnvVar } from '../../../../setup/set-env.js';
const skill = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const pins = JSON.parse(fs.readFileSync(path.join(skill, 'versions.json'), 'utf8'));
const secret = () => randomBytes(32).toString('hex');
export function controlPaths(root = process.cwd()) {
const slug = getInstallSlug(root);
const directory = path.join(root, 'data', 'session-materials', 'iron-control');
return {
directory,
project: `nanoclaw-iron-control-${slug}`,
network: `nanoclaw-iron-control-${slug}`,
compose: path.join(directory, 'compose.yaml'),
environment: path.join(directory, 'control.env'),
databaseEnvironment: path.join(directory, 'database.env'),
proxyEnvironment: path.join(directory, 'proxy.env'),
registration: path.join(directory, 'registration.json'),
login: path.join(directory, 'login.txt'),
};
}
function writePrivate(file: string, text: string): void {
fs.writeFileSync(file, text, { mode: 0o600 });
fs.chmodSync(file, 0o600);
}
export function controlPort(root: string): number {
const env = fs.existsSync(path.join(root, '.env')) ? fs.readFileSync(path.join(root, '.env'), 'utf8') : '';
const port = Number(
process.env.NANOCLAW_IRON_CONTROL_PORT || env.match(/^NANOCLAW_IRON_CONTROL_PORT=(.*)$/m)?.[1] || 10257,
);
if (!Number.isInteger(port) || port < 1 || port > 65535)
throw new Error('Iron Control port must be between 1 and 65535');
return port;
}
export function controlCompose(root: string, port: number): string {
const p = controlPaths(root);
// Same labels as the central proxy: the install label lets uninstall remove
// this project's volume and network; the role keeps the host's residue
// reaping off a running gateway. Never on the volume: Compose would offer
// to recreate an existing one (data loss) when its labels change.
const labels = { [LABELS.install]: getInstallSlug(root), [LABELS.role]: GATEWAY_ROLE };
return yaml({
name: p.project,
services: {
database: {
image: pins['iron-control-postgres-image'],
restart: 'unless-stopped',
labels,
env_file: [p.databaseEnvironment],
volumes: ['database:/var/lib/postgresql/data'],
healthcheck: { test: ['CMD-SHELL', 'pg_isready -U iron_control'], interval: '2s', timeout: '3s', retries: 30 },
},
web: {
image: pins['iron-control-image'],
platform: pins['iron-control-platform'],
restart: 'unless-stopped',
labels,
env_file: [p.environment],
command: ['./bin/rails', 'server'],
ports: [`127.0.0.1:${port}:3000`],
depends_on: { database: { condition: 'service_healthy' } },
healthcheck: {
test: ['CMD', 'curl', '-fsS', 'http://127.0.0.1:3000/up'],
interval: '3s',
timeout: '5s',
retries: 60,
start_period: '30s',
},
},
},
volumes: { database: {} },
networks: { default: { name: p.network } },
});
}
async function compose(root: string, args: string[]): Promise<void> {
const p = controlPaths(root);
await installCommand('docker', ['compose', '-p', p.project, '-f', p.compose, ...args], {
label: args[0] === 'up' ? 'Pull and start Iron Control and database' : 'Stop Iron Control',
timeoutMs: 360_000,
failureHint:
'Check Docker and access to the pinned console/database images. Registry permissions require authentication on this machine. Existing database and keys have been kept; retry after fixing access.',
});
}
function readEnvironment(root: string): Record<string, string> {
return Object.fromEntries(
fs
.readFileSync(controlPaths(root).environment, 'utf8')
.trim()
.split('\n')
.map((line) => {
const eq = line.indexOf('=');
return [line.slice(0, eq), line.slice(eq + 1)];
}),
);
}
export class IronControlRequestError extends Error {
constructor(
message: string,
readonly status: number,
) {
super(message);
}
}
/** Calls the official local API; never returns credentials to an agent. */
export async function controlRequest(root: string, resource: string, method = 'GET', data?: unknown): Promise<any> {
const p = controlPaths(root);
const env = readEnvironment(root);
const response = await fetch(`http://127.0.0.1:${controlPort(root)}/api/v1/${resource}`, {
method,
headers: { Authorization: `Bearer ${env.IRON_CONTROL_INITIAL_API_KEY}`, 'Content-Type': 'application/json' },
...(data === undefined ? {} : { body: JSON.stringify({ data }) }),
signal: AbortSignal.timeout(15_000),
redirect: 'error',
});
if (!response.ok)
throw new IronControlRequestError(
`Iron Control ${method} ${resource} failed (${response.status}); inspect ${p.project} logs`,
response.status,
);
return response.status === 204 ? null : ((await response.json()) as { data: unknown }).data;
}
export async function installControl(root = process.cwd()): Promise<void> {
const p = controlPaths(root);
const port = controlPort(root);
const url = `http://127.0.0.1:${port}`;
fs.mkdirSync(p.directory, { recursive: true, mode: 0o700 });
fs.chmodSync(p.directory, 0o700);
if (!fs.existsSync(p.environment)) {
const volumes = await installCommand('docker', ['volume', 'ls', '--format', '{{.Name}}'], {
label: 'Check existing Iron Control data',
timeoutMs: 15_000,
capture: true,
});
// A folder deleted by hand leaves the containers and volume behind, and
// the same path derives the same names; setup never removes them itself.
if (volumes.trim().split('\n').includes(`${p.project}_database`))
throw new Error(
`Iron Control database exists but its encryption keys are missing; restore ${p.environment}, ` +
`or delete the old database and every credential stored in it with: ` +
`docker rm -f ${p.project}-database-1 ${p.project}-web-1; docker volume rm ${p.project}_database`,
);
const password = secret();
const email = 'operator@nanoclaw.local';
const databasePassword = secret();
const env = {
RAILS_ENV: 'production',
SECRET_KEY_BASE: secret(),
IRON_CONTROL_AR_ENCRYPTION_PRIMARY_KEY: secret(),
IRON_CONTROL_AR_ENCRYPTION_DETERMINISTIC_KEY: secret(),
IRON_CONTROL_AR_ENCRYPTION_KEY_DERIVATION_SALT: secret(),
IRON_CONTROL_DB_HOST: 'database',
IRON_CONTROL_DATABASE_PASSWORD: databasePassword,
IRON_CONTROL_INITIAL_USER_EMAIL: email,
IRON_CONTROL_INITIAL_USER_PASSWORD: password,
IRON_CONTROL_INITIAL_API_KEY: `iak_${secret()}`,
IRON_CONTROL_SOLID_QUEUE_IN_PUMA: 'true',
};
writePrivate(
p.environment,
Object.entries(env)
.map(([key, value]) => `${key}=${value}`)
.join('\n') + '\n',
);
writePrivate(p.login, `Email: ${email}\nPassword: ${password}\n`);
}
const environment = readEnvironment(root);
writePrivate(
p.databaseEnvironment,
`POSTGRES_USER=iron_control\nPOSTGRES_PASSWORD=${environment.IRON_CONTROL_DATABASE_PASSWORD}\n`,
);
// Keep encryption and account keys unchanged on every refresh.
writePrivate(p.compose, controlCompose(root, port));
await compose(root, ['up', '-d', '--wait', '--wait-timeout', '240']);
let registration: { principalId: string; proxyId: string };
if (fs.existsSync(p.registration)) {
registration = JSON.parse(fs.readFileSync(p.registration, 'utf8'));
await controlRequest(root, `proxies/${registration.proxyId}`);
if (!fs.existsSync(p.proxyEnvironment))
throw new Error('Iron proxy token file is missing; restore it before reconnecting');
} else {
const principal = await controlRequest(root, 'principals/nanoclaw', 'PUT', {
namespace: getInstallSlug(root),
name: 'NanoClaw',
});
const proxy = await controlRequest(root, 'proxies', 'POST', {
name: `NanoClaw ${getInstallSlug(root)}`,
principal_id: principal.id,
});
writePrivate(p.proxyEnvironment, `IRON_PROXY_TOKEN=${proxy.token}\nIRON_CONTROL_PLANE_URL=http://web:3000\n`);
registration = { principalId: principal.id, proxyId: proxy.id };
writePrivate(p.registration, JSON.stringify(registration, null, 2) + '\n');
}
upsertEnvVar('NANOCLAW_IRON_CONTROL_PORT', String(port), root);
upsertEnvVar('NANOCLAW_IRON_CONTROL_URL', url, root);
console.log(`Official Iron Control: ${url}\nLocal login details: ${p.login}`);
}
export async function removeControl(root = process.cwd()): Promise<void> {
if (fs.existsSync(controlPaths(root).compose)) await compose(root, ['down']);
}
export async function grantSecret(kind: string, id: string, root = process.cwd()): Promise<void> {
const fields: Record<string, string> = {
static: 'static_secret_id',
gcp: 'gcp_auth_secret_id',
aws: 'aws_auth_secret_id',
oauth: 'oauth_token_secret_id',
postgres: 'pg_dsn_secret_id',
hmac: 'hmac_secret_id',
};
if (!fields[kind]) throw new Error('Secret kind must be static, gcp, aws, oauth, postgres, or hmac');
const { principalId } = JSON.parse(fs.readFileSync(controlPaths(root).registration, 'utf8'));
for (let page = 1; ; page++) {
const grants = await controlRequest(root, `principals/${principalId}/grants?limit=200&page=${page}`);
if (grants.some((grant: Record<string, string>) => grant[fields[kind]] === id)) return;
if (grants.length < 200) break;
}
await controlRequest(root, 'grants', 'POST', { principal_id: principalId, [fields[kind]]: id });
console.log('Credential granted to this NanoClaw install. Iron Proxy will sync it automatically.');
}
export async function storeModelCredential(value: string, host: string, root: string, authEnv?: string): Promise<void> {
await assertCredentialIsolation(root, {
host,
headers: ['Authorization', 'x-api-key'],
proxyValue: 'gateway-managed',
ownedForeignIds: ['nanoclaw-model'],
});
const credential = await controlRequest(root, 'static_secrets/nanoclaw-model', 'PUT', {
namespace: getInstallSlug(root),
name: authEnv ? `NanoClaw model (${authEnv})` : 'NanoClaw model',
source: { source_type: 'control_plane', secret: value, config: {} },
inject_config: {},
replace_config: { proxy_value: 'gateway-managed', match_headers: ['Authorization', 'X-Api-Key'], require: false },
// CONNECT establishes the tunnel before the SDK sends its auth header.
// Require replacement only on the inner HTTP requests.
rules: [{ host, http_methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'] }],
});
await grantSecret('static', credential.id, root);
}
if (
process.argv[1] &&
fs.existsSync(process.argv[1]) &&
import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href
) {
const [command, kind, id] = process.argv.slice(2);
const run = async () => {
if (command === 'grant' && kind && id) await grantSecret(kind, id);
else if (command === 'remove') await removeControl();
else if (command === 'status') {
const p = controlPaths();
console.log(
`Official Iron Control: http://127.0.0.1:${controlPort(process.cwd())}\nLocal login details: ${p.login}`,
);
} else
throw new Error(
'Use setup.ts --with-control to install; control.ts accepts status, grant <kind> <id>, or remove',
);
};
void run().catch((error) => {
console.error(error.message);
process.exitCode = 1;
});
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |