Runtime Reference

The Kiwi Runtime (kiwi-runtime) connects the cloud AI to your local machine. It's the process that lets the AI read files, write code, run commands, and search your codebase — all on your machine.

Quick Start

# Default: restricted to current directory
kiwi-runtime connect

# Allow access to additional directories
kiwi-runtime connect --allow /tmp --allow /var/log

# Full filesystem access
kiwi-runtime connect --scope full

Options

What the Runtime Can Do

When the runtime is connected, the AI can perform these operations on your machine:

Read & Search

• Read files — full content, specific line ranges, or grep within files
• Search across files — recursive search with glob patterns and context lines
• List directories — browse your project structure
• Get file info — size, permissions, timestamps

Write & Edit

• Create files — write new files with automatic parent directory creation
• Edit files — find-and-replace, line range replacement, insert at line, apply diffs
• Append to files — add content to existing files
• Large file support — chunked writing for files too large for a single message

Manage Files

• Move and rename files and directories
• Copy files and directories (recursive)
• Delete files and directories
• Create directories

Run Commands

• Shell commands — run any command with timeout protection and output streaming
• Interactive commands — PTY support for commands that need input (like npm login or gh auth login)

Scope Modes

Restricted (Default)

The AI can only access files in your current directory. This is the safe default.

kiwi-runtime connect --scope restricted

Add specific directories with --allow:

kiwi-runtime connect --allow /tmp --allow ~/shared-configs

Full

The AI can access any file on your system. Use when you need cross-project access.

kiwi-runtime connect --scope full

Viewing Runtime Logs

See what the runtime is doing in real time:

• In the TUI: Press Ctrl+O or type /show-logs
• Interactive input: Type directly in the logs screen when a command needs input
• Interrupt: Press Ctrl+K to stop a running command

Lifecycle

With the TUI

The TUI manages the runtime automatically:

1. You launch kiwi
2. The TUI spawns kiwi-runtime in the background
3. The runtime connects to the backend
4. When you send a message, the AI can execute commands through the runtime
5. On exit, you're prompted to keep or stop running runtimes

Standalone (with Web Dashboard)

Run the runtime manually for browser-based access:

1. You run kiwi-runtime connect --scope full
2. The runtime connects and waits
3. You open kiwicode.ai/autocode/new and ask the AI to connect
4. The AI binds to your runtime and starts executing

Press Ctrl+C to disconnect.

Troubleshooting

Runtime not starting

Check authentication:

kiwi whoami

If not authenticated, run kiwi login first.

"Permission denied" in restricted mode

Add the directory with --allow:

kiwi-runtime connect --allow /path/to/dir

Or switch to full mode:

kiwi-runtime connect --scope full

Interactive command hangs

Open Runtime Logs (Ctrl+O) — the command may be waiting for your input. Type directly in the logs screen. Press Ctrl+K to interrupt.

WebSocket disconnects

The TUI automatically detects disconnects and respawns the runtime. For standalone runtimes, restart manually:

kiwi-runtime connect