feat: configurable agent bind host (#166)

Author: gricha

docs/docs/configuration/overview.md

@@ -23,6 +23,7 @@ Location: `~/.config/perry/config.json`
 ```json
 {
   "port": 7391,
+  "host": "0.0.0.0",
   "credentials": {
     "env": {
       "ANTHROPIC_API_KEY": "sk-ant-...",
@@ -116,6 +117,27 @@ perry config agent myserver.tail1234.ts.net
 
 If you run any `perry` command without configuring an agent (and no local agent is running), Perry will interactively prompt you for the agent hostname.
 
+## Bind Host
+
+The `host` setting controls which network interface the agent listens on.
+
+| Value | Description |
+|-------|-------------|
+| `0.0.0.0` | All interfaces (default) — accessible from other devices on the network |
+| `127.0.0.1` | Localhost only — only accessible from this machine |
+| Custom IP | Bind to a specific network interface |
+
+You can set this via:
+
+- **Config file**: `"host": "127.0.0.1"` in `config.json`
+- **CLI flag**: `perry agent run --host 127.0.0.1`
+- **Environment variable**: `PERRY_HOST=127.0.0.1`
+- **Setup wizard**: `perry agent config` (Network step)
+
+Priority: CLI flag > `PERRY_HOST` env var > config file > `0.0.0.0`
+
+Use `127.0.0.1` if you only access Perry from the same machine, or if corporate security policies flag services listening on all interfaces. Use `0.0.0.0` if you need remote access (e.g., via Tailscale or from other machines on the LAN).
+
 ## Configuration Sections
 
 - [Credentials](./credentials.md) - Env vars, files, and SSH keys

src/agent/run.ts

@@ -45,6 +45,7 @@ function createAgentServer(
   configDir: string,
   config: AgentConfig,
   port: number,
+  hostname: string,
   tailscale?: TailscaleInfo
 ) {
   sessionManager.init(configDir);
@@ -120,7 +121,7 @@ function createAgentServer(
 
   const server = Bun.serve<WebSocketData>({
     port,
-    hostname: '::',
+    hostname,
 
     async fetch(req, server) {
       const url = new URL(req.url);
@@ -229,6 +230,7 @@ function createAgentServer(
 
 export interface StartAgentOptions {
   port?: number;
+  host?: string;
   configDir?: string;
   noHostAccess?: boolean;
 }
@@ -295,12 +297,14 @@ export async function startAgent(options: StartAgentOptions = {}): Promise<void>
   const port =
     options.port || parseInt(process.env.PERRY_PORT || '', 10) || config.port || DEFAULT_AGENT_PORT;
 
+  const host = options.host || process.env.PERRY_HOST || config.host || '0.0.0.0';
+
   console.log(BANNER);
   console.log(`  Documentation: https://gricha.github.io/perry/getting-started`);
   console.log(`  Web UI: http://localhost:${port}`);
   console.log('');
   console.log(`[agent] Config directory: ${configDir}`);
-  console.log(`[agent] Starting on port ${port}...`);
+  console.log(`[agent] Binding to ${host}:${port}...`);
 
   const tailscale = await getTailscaleStatus();
   let tailscaleServeActive = false;
@@ -340,7 +344,7 @@ export async function startAgent(options: StartAgentOptions = {}): Promise<void>
   let terminalHandler: TerminalHandler;
 
   try {
-    const result = createAgentServer(configDir, config, port, tailscaleInfo);
+    const result = createAgentServer(configDir, config, port, host, tailscaleInfo);
     server = result.server;
     fileWatcher = result.fileWatcher;
     terminalHandler = result.terminalHandler;

src/cli/setup-wizard.tsx

@@ -6,16 +6,17 @@ import { loadAgentConfig, saveAgentConfig, getConfigDir, ensureConfigDir } from
 import { discoverSSHKeys } from '../ssh';
 import type { SSHKeyInfo } from '../shared/client-types';
 
-type Step = 'welcome' | 'auth' | 'github' | 'ssh' | 'tailscale' | 'complete';
+type Step = 'welcome' | 'auth' | 'github' | 'ssh' | 'tailscale' | 'network' | 'complete';
 
-const STEPS: Step[] = ['welcome', 'auth', 'github', 'ssh', 'tailscale', 'complete'];
+const STEPS: Step[] = ['welcome', 'auth', 'github', 'ssh', 'tailscale', 'network', 'complete'];
 
 interface WizardState {
   authToken: string;
   authTokenGenerated: boolean;
   githubToken: string;
   selectedSSHKeys: string[];
   tailscaleAuthKey: string;
+  bindHost: string;
 }
 
 function WelcomeStep({ onNext }: { onNext: () => void }) {
@@ -38,6 +39,7 @@ function WelcomeStep({ onNext }: { onNext: () => void }) {
         <Text>• Git access (GitHub token)</Text>
         <Text>• SSH keys for workspaces</Text>
         <Text>• Tailscale networking</Text>
+        <Text>• Network bind host</Text>
       </Box>
       <Box marginTop={1}>
         <Text color="gray">Press Enter to continue...</Text>
@@ -246,6 +248,133 @@ function SSHKeySelectStep({
   );
 }
 
+type BindHostOption = '0.0.0.0' | '127.0.0.1' | 'custom';
+
+const BIND_HOST_OPTIONS: { value: BindHostOption; label: string; description: string }[] = [
+  {
+    value: '0.0.0.0',
+    label: 'All interfaces (0.0.0.0)',
+    description: 'Accessible from other devices on the network',
+  },
+  {
+    value: '127.0.0.1',
+    label: 'Localhost only (127.0.0.1)',
+    description: 'Only accessible from this machine',
+  },
+  { value: 'custom', label: 'Custom', description: 'Enter a custom hostname or IP' },
+];
+
+function NetworkStep({
+  value,
+  onChange,
+  onNext,
+  onBack,
+}: {
+  value: string;
+  onChange: (value: string) => void;
+  onNext: () => void;
+  onBack: () => void;
+}) {
+  const currentOption: BindHostOption =
+    value === '0.0.0.0' ? '0.0.0.0' : value === '127.0.0.1' ? '127.0.0.1' : 'custom';
+  const isCustom = currentOption === 'custom';
+  const [highlighted, setHighlighted] = useState(
+    Math.max(
+      0,
+      BIND_HOST_OPTIONS.findIndex((o) => o.value === currentOption)
+    )
+  );
+  const [editingCustom, setEditingCustom] = useState(false);
+  const [customValue, setCustomValue] = useState(isCustom ? value : '');
+
+  useInput((input, key) => {
+    if (editingCustom) {
+      if (key.return) {
+        if (customValue.trim()) {
+          onChange(customValue.trim());
+        }
+        setEditingCustom(false);
+      } else if (key.escape) {
+        setEditingCustom(false);
+      }
+      return;
+    }
+
+    if (key.upArrow) {
+      setHighlighted((h) => Math.max(0, h - 1));
+    } else if (key.downArrow) {
+      setHighlighted((h) => Math.min(BIND_HOST_OPTIONS.length - 1, h + 1));
+    } else if (input === ' ' || key.return) {
+      const selected = BIND_HOST_OPTIONS[highlighted];
+      if (selected.value === 'custom') {
+        setEditingCustom(true);
+      } else {
+        onChange(selected.value);
+        if (key.return) {
+          onNext();
+          return;
+        }
+      }
+    } else if (key.escape) {
+      onBack();
+    }
+  });
+
+  return (
+    <Box flexDirection="column" gap={1}>
+      <Text bold>Bind Host</Text>
+      <Text color="gray">
+        Choose which network interface the agent listens on. Use localhost to restrict access to
+        this machine only.
+      </Text>
+      <Box flexDirection="column" marginTop={1}>
+        {BIND_HOST_OPTIONS.map((option, index) => (
+          <Box key={option.value}>
+            <Text color={highlighted === index ? 'cyan' : undefined}>
+              <Text
+                color={
+                  option.value === currentOption || (option.value === 'custom' && isCustom)
+                    ? 'green'
+                    : 'gray'
+                }
+              >
+                {option.value === currentOption || (option.value === 'custom' && isCustom)
+                  ? '(*) '
+                  : '( ) '}
+              </Text>
+              <Text>{option.label}</Text>
+              <Text color="gray"> — {option.description}</Text>
+            </Text>
+          </Box>
+        ))}
+      </Box>
+      {editingCustom && (
+        <Box marginTop={1}>
+          <Text>Host: </Text>
+          <TextInput
+            value={customValue}
+            onChange={setCustomValue}
+            placeholder="e.g. 192.168.1.100"
+          />
+        </Box>
+      )}
+      {isCustom && !editingCustom && value && (
+        <Box marginTop={1}>
+          <Text>Current: </Text>
+          <Text color="cyan">{value}</Text>
+        </Box>
+      )}
+      <Box marginTop={1}>
+        <Text color="gray">
+          {editingCustom
+            ? 'Enter to confirm, Esc to cancel'
+            : 'Space to select, Enter to continue, Esc to go back'}
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+
 function CompleteStep({ state, onFinish }: { state: WizardState; onFinish: () => void }) {
   useInput((_input, key) => {
     if (key.return) {
@@ -259,6 +388,8 @@ function CompleteStep({ state, onFinish }: { state: WizardState; onFinish: () =>
   if (state.selectedSSHKeys.length > 0)
     configured.push(`${state.selectedSSHKeys.length} SSH key(s)`);
   if (state.tailscaleAuthKey) configured.push('Tailscale');
+  if (state.bindHost && state.bindHost !== '0.0.0.0')
+    configured.push(`Bind host: ${state.bindHost}`);
 
   return (
     <Box flexDirection="column" gap={1}>
@@ -310,6 +441,7 @@ function SetupWizard() {
     githubToken: '',
     selectedSSHKeys: [],
     tailscaleAuthKey: '',
+    bindHost: '0.0.0.0',
   });
   const [saving, setSaving] = useState(false);
 
@@ -331,6 +463,7 @@ function SetupWizard() {
         githubToken: config.agents?.github?.token || '',
         selectedSSHKeys: config.ssh?.global.copy || [],
         tailscaleAuthKey: config.tailscale?.authKey || '',
+        bindHost: config.host || '0.0.0.0',
       }));
     };
     loadExisting().catch(() => {});
@@ -404,6 +537,10 @@ function SetupWizard() {
         };
       }
 
+      if (state.bindHost) {
+        config.host = state.bindHost;
+      }
+
       await saveAgentConfig(config, configDir);
     } catch {
       // Ignore save errors - user can reconfigure later
@@ -472,6 +609,14 @@ function SetupWizard() {
               optional
             />
           )}
+          {step === 'network' && (
+            <NetworkStep
+              value={state.bindHost}
+              onChange={(v) => setState((s) => ({ ...s, bindHost: v }))}
+              onNext={nextStep}
+              onBack={prevStep}
+            />
+          )}
           {step === 'complete' && (
             <CompleteStep
               state={state}

src/config/loader.ts

@@ -18,6 +18,7 @@ export async function ensureConfigDir(configDir?: string): Promise<void> {
 export function createDefaultAgentConfig(): AgentConfig {
   return {
     port: DEFAULT_AGENT_PORT,
+    host: '0.0.0.0',
     credentials: {
       env: {},
       files: {},
@@ -79,6 +80,7 @@ export async function loadAgentConfig(configDir?: string): Promise<AgentConfig>
       : config.tailscale;
     return {
       port: config.port || DEFAULT_AGENT_PORT,
+      host: config.host || '0.0.0.0',
       credentials: {
         env: config.credentials?.env || {},
         files: config.credentials?.files || {},

src/index.ts

@@ -45,11 +45,13 @@ agentCmd
   .command('run')
   .description('Start the agent daemon')
   .option('-p, --port <port>', 'Port to listen on', parseInt)
+  .option('--host <host>', 'Host to bind to')
   .option('-c, --config-dir <dir>', 'Configuration directory')
   .option('--no-host-access', 'Disable direct host machine access')
   .action(async (options) => {
     await startAgent({
       port: options.port,
+      host: options.host,
       configDir: options.configDir,
       noHostAccess: options.hostAccess === false,
     });

src/shared/types.ts

@@ -108,6 +108,7 @@ export interface McpServerDefinition {
 
 export interface AgentConfig {
   port: number;
+  host?: string;
   credentials: WorkspaceCredentials;
   scripts: WorkspaceScripts;
   agents?: CodingAgents;