RespCode Documentation

Multi-model AI code generation with real hardware verification.

RespCode orchestrates multiple AI models (Claude, GPT, DeepSeek, Gemini, and more) to generate, compile, and verify code across multiple architectures — x86, ARM64, and ARM32 baremetal — using Daytona sandboxes and Firecracker microVMs.

Quick Start

Hardware Agent (recommended for embedded development)

Web Platform

Visit respcode.com, sign up, and start generating code immediately in your browser. The web platform is free with unlimited generations.

---

Hardware Agent

Generate code in the cloud. Deploy and verify on real hardware.

The RespCode Hardware Agent is a CLI tool that connects your physical development boards to the RespCode cloud. It generates code using AI models, compiles in sandboxes, then deploys the binary to your actual hardware — STM32, NXP, Nordic, Pico, TI, Microchip and other ARM development boards via pyOCD/UF2, Linux Single Board computer via SSH, test Cloud instances or your local machine directly.

Installation

One-line install (Linux & macOS)

This will:

• Detect your OS and CPU architecture (x86 or ARM64)
• Download the correct binary to ~/.local/bin/
• Add it to your PATH
• Create a default config at ~/.config/respcode/boards.yaml
• Linux only: install udev rules for USB debug probes (ST-Link, CMSIS-DAP, J-Link, NXP)
• Linux only: add your user to dialout and plugdev groups
• Scan USB for connected development boards (Linux via sysfs, macOS via system_profiler)
• Auto-detect STM32, NXP, Nordic, Pico, TI, Microchip, and J-Link debug probes
• Install pyOCD target packs for detected MCUs

Supported platforms

OS	Architecture	Binary
Linux	x86_64	respcode-agent-linux-amd64
Linux	ARM64	respcode-agent-linux-arm64
macOS	Apple Silicon	respcode-agent-darwin-arm64
macOS	Intel	respcode-agent-darwin-amd64

Manual install

Verify installation

First Run & API Key

When you first run the agent, it will show the board picker and prompt for your API key:

Get your API key at: respcode.com/settings/api-keys

Configuration

The agent reads its configuration from boards.yaml. It searches these locations in order:

1. Explicit --config path/to/boards.yaml flag
2. Current working directory: ./boards.yaml
3. XDG config: ~/.config/respcode/boards.yaml
4. Same directory as the binary

The install script creates the default config at ~/.config/respcode/boards.yaml:

respcode:
  api_url: "https://respcode.com/api"
  api_key: "${RESPCODE_API_KEY}"     # set via /key command or env var

agent:
  max_retries: 3                    # retry attempts on failure
  uart_timeout_seconds: 10
  flash_timeout_seconds: 30
  output_dir: "respcode-output"     # where artifacts are saved

boards:
  - id: "local"
    type: "sbc"
    board_name: "Local Machine"
    architecture: "x86"             # auto-detected during install
    connection: "localhost"
    verify:
      timeout: 30

Adding Boards

Add boards by editing boards.yaml or using the /boards commands inside the agent. The agent supports three board types and auto-detects USB boards on every startup.

Baremetal MCU (Flash + UART)

For microcontrollers like STM32, NXP and other ARM baremetal MCU using pyOCD. The agent first compiles the binary in cloud, verifies there are no errors and later uses pyOCD to flash firmware and reads UART output for verification.

  - id: "nucleo-f767zi"
    type: "bare-metal"
    mcu: "STM32F767ZI"
    board_name: "NUCLEO-F767ZI"
    architecture: "arm32-baremetal"
    flash:
      tool: "pyocd"
      target: "stm32f767zi"          # pyocd target name
      address: "0x08000000"          # flash start address
      interface: "stlink"           # stlink, cmsis-dap, jlink
      speed_khz: 4000
    uart:
      port: "/dev/ttyACM0"           # ls /dev/ttyACM* to find yours
      baud: 115200
    board_info:
      led_pin: "PB0"
      led_active: "high"
      uart_pins: "PD8 (TX) / PD9 (RX) on USART3"
      clock: "216MHz HSE"
      ram: "512KB @ 0x20000000"
      flash_size: "2MB"

Required fields for baremetal:

Field	Description	Example
type	Must be "bare-metal"	bare-metal
mcu	MCU part number (used in prompt enrichment)	STM32F767ZI
architecture	arm32-baremetal	arm32-baremetal
flash.tool	pyocd, uf2, or openocd	pyocd
flash.target	pyOCD target ID	stm32f767zi
uart.port	Serial port path	/dev/ttyACM0
board_info.led_pin	LED pin name (for prompts)	PB0
board_info.uart_pins	UART pin description (for prompts)	PD8/PD9 on USART3

SBC via SSH

For single-board computers like Raspberry Pi, Jetson, BeagleBone, or any Linux machine reachable via SSH. Code is first compiled and executed in the cloud sandbox, then SCP'd to the target and executed via SSH. Use /boards ssh in the agent for an interactive setup wizard with presets for common boards.

  - id: "rpi4"
    type: "sbc"
    board_name: "Raspberry Pi 4"
    architecture: "arm64"          # or "arm32" for 32-bit OS
    ssh:
      host: "192.168.1.50"
      user: "pi"
      key: "~/.ssh/id_rsa"          # path to private key
      port: 22
    verify:
      timeout: 10                  # execution timeout in seconds
      expect: ""                   # optional: expected output pattern

Localhost

Run code directly on your local machine without SSH. Code is compiled in the cloud, downloaded, and executed locally. Great for quick testing.

  - id: "local"
    type: "sbc"
    board_name: "Local Machine"
    architecture: "x86"             # or "arm64" on Apple Silicon / ARM Linux
    connection: "localhost"
    verify:
      timeout: 30

Raspberry Pi Pico (UF2)

For RP2040-based boards that flash via UF2 mass storage. Hold BOOTSEL while plugging in — the board mounts as a USB drive, and the agent copies the UF2 binary directly.

  - id: "rpi-pico"
    type: "bare-metal"
    mcu: "RP2040"
    board_name: "Raspberry Pi Pico"
    architecture: "arm32"
    flash:
      tool: "uf2"
      mount: "/Volumes/RPI-RP2"      # macOS — use /mnt/rpi-rp2 on Linux
    uart:
      port: "/dev/cu.usbmodem1101"  # CDC USB serial
      baud: 115200
    board_info:
      led_pin: "GPIO25"
      led_active: "high"
      uart_pins: "UART0 on GP0 (TX) / GP1 (RX)"
      clock: "125MHz from XOSC 12MHz + PLL"
      ram: "264KB @ 0x20000000"
      flash_size: "2MB @ 0x10000000"

Nordic nRF (pyOCD)

For Nordic nRF52/nRF53 development kits with on-board J-Link or CMSIS-DAP debug probe.

  - id: "nrf52840"
    type: "bare-metal"
    mcu: "NRF52840"
    board_name: "nRF52840-DK"
    architecture: "arm32-baremetal"
    flash:
      tool: "pyocd"
      target: "nrf52840"
      address: "0x00000000"
      interface: "cmsis-dap"
    uart:
      port: "/dev/ttyACM0"
      baud: 115200

Auto-Detection

The agent automatically detects new USB boards every time it starts. If you plug in a board after installation, just restart the agent — it will find the board, add it to boards.yaml, and install the required pyOCD target pack.

Supported debug probes (auto-detected on Linux & macOS)

Board Family	USB Vendor ID	Flash Tool	Examples
STM32	0x0483	pyOCD (ST-Link)	Nucleo-F767ZI, Discovery, Nucleo-F411RE
NXP LPC	0x1fc9	pyOCD (CMSIS-DAP)	LPC55S69-EVK, LPCXpresso
CMSIS-DAP	0x0d28	pyOCD	mbed-enabled boards
Raspberry Pi Pico	0x2e8a	UF2 copy	Pico, Pico W, Pico 2
Nordic nRF	0x1915	pyOCD	nRF52840-DK, nRF5340-DK
TI	0x0451	OpenOCD	MSP432, CC3220, TM4C
SEGGER J-Link	0x1366	J-Link	Any J-Link connected target
Microchip / Atmel	0x03eb	OpenOCD	SAM, PIC32

Adding SBC targets interactively

For SSH-based boards (Raspberry Pi, Jetson, BeagleBone, cloud instances), use the built-in wizard:

The wizard prefills board name, architecture, and SSH username from the preset. You only need to enter the IP address and SSH key path. It also tests the connection and auto-detects the remote architecture via uname -m.

Modes & Tiers

After connecting, select your mode and tier at the prompt. Use shortcodes like C1, S2, C4:

Shortcode	Mode	Tier	Credits	Models
C1	Compete	Flagship	29	Claude Opus, GPT-5, Gemini 3 Pro, DeepSeek Coder
C2	Compete	Mid	17	Claude Sonnet, GPT-4o, Gemini Flash, DeepSeek V3
C3	Compete	Budget	6	Claude Haiku, GPT-4o Mini, Gemini Flash
C4	Compete	Open Source	8	Llama 4, Qwen 3, DeepSeek, Mistral
S1	Single	Flagship	varies	Pick one model from flagship tier

Change mode anytime with /mode.

Commands Reference

Command	Description
<any prompt>	Generate code, compile, and deploy
rerun	Re-run the last prompt (new generation)
Hardware
flash <path>	Flash a local .bin file and verify via UART
reflash	Re-download and flash the last successful generation
uart	Listen on UART (no flash)
probe	Check if target is connected
ports	List available serial ports
Cloud
download <gen_id>	Download all artifacts for a generation
status	Show board + cloud status
Session
/key	Set or change your API key
/mode	Change mode (compete/single) and tier
/board	Switch to a different board
/boards	List configured boards and management commands
/boards ssh	Interactive wizard to add SBC targets (Pi, Jetson, BeagleBone...)
/boards add	Add a board interactively
/boards probe	Auto-detect MCU via pyOCD and update config
/boards remove N	Remove board #N from config
results	Show compile results from last generation
history	Show last prompt and generation info
help	Show all commands
quit	Exit the agent

Workflow

Here's what happens when you type a prompt:

The 3-attempt retry system:

1. Attempt 1: Normal compete/single generation
2. Attempt 2: If all models fail — Claude Sonnet reviews the errors and generates a fix
3. Attempt 3: If still failing — Claude Opus escalation with full error context

Deploy & Verify

Baremetal flow

For type: "bare-metal" boards:

1. Code compiles in cloud sandbox (Docker + QEMU verification)
2. Binary downloads to agent
3. pyOCD flashes to board memory
4. UART monitored for output
5. Output compared against expected pattern

SBC / SSH flow

For type: "sbc" boards with SSH:

1. Code compiles + runs in cloud sandbox
2. If sandbox passes → binary SCP'd to target
3. SSH executes binary on target
4. stdout captured for verification

Localhost flow

For connection: "localhost":

1. Code compiles + runs in cloud sandbox
2. Binary downloaded to ~/respcode-deploy/
3. Executed directly on local machine
4. stdout captured for verification

The agent auto-detects the file type and uses the right interpreter: .py → python3, .js → node, .rb → ruby, ELF → direct execution.

Auto-Update

On every startup, the agent checks https://respcode.com/agent/version.json for new versions. If a newer version is available, it downloads, verifies the SHA-256 checksum, replaces itself, and exits with a "please restart" message.

To manually update:

Troubleshooting

pyOCD not detecting my board

• Run probe in the agent to check connection
• Run ports to list serial ports
• Ensure udev rules are installed (Linux): ls /etc/udev/rules.d/99-respcode.rules
• Check group membership (Linux): groups — should include dialout and plugdev
• Unplug and replug your board

SSH connection fails

• Verify SSH manually: ssh -i ~/.ssh/key user@host echo ok
• Check that ssh.key path is correct and readable
• Ensure the target is on the same network

Compilation fails in sandbox

• Check results for detailed error output
• The agent retries up to 3 times with escalating model intelligence
• Try rephrasing your prompt with more specific requirements

macOS Gatekeeper warning

"Permission denied" on serial port (Linux)

macOS: pyOCD not found after install

On macOS, pip install places binaries in ~/Library/Python/3.XX/bin/ which may not be in your PATH. The agent searches common locations automatically, but if you need to run pyOCD manually:

macOS: boards.yaml not created during install

If the install script fails to create the config file, the agent will auto-create a default one on first run with a localhost target. To add boards afterwards, use /boards ssh or /boards add inside the agent.

macOS: Board not detected during install

Ensure your board is plugged in before running the install script. The installer uses system_profiler SPUSBDataType to detect debug probes on macOS. If you plug in the board after installing, just restart the agent — it auto-detects new boards on every startup.

Agent shows "Plan: —" (empty)

This happens when the plan field hasn't been set for your user account on the server. Contact support or check that the server migration has been applied. The agent still works normally — this is a display-only issue.

Uninstall the agent

Examples

Example 1: Bare-metal Ethernet UDP on STM32F767ZI

Flagship Compete mode generating bare-metal Ethernet firmware. 4 models attempt to write a UDP sender using the LAN8742A PHY over RMII — direct register access, no HAL. Claude Opus compiles and sends real UDP packets on the wire.

Example 2: Memory bandwidth test on ARM64 cloud instance

Running 4 open-source models in Compete mode on a remote ARM64 instance via SSH. Each model generates a C program that measures memcpy bandwidth on a 64MB buffer.

Example 3: Baremetal LED blink and UART initialization on NXP LPC55S69-EVK

Compete mode with 4 models generating bare-metal firmware. The agent enriches the prompt with register-level SVD data (5 peripherals, 227 registers, 64 pins) for the LPC55S69 MCU — ensuring models use correct register addresses instead of guessing.

Example 4: Hello World locally on x86

The simplest test — generate a C program and run it directly on your machine. No hardware needed.

---

Web Platform

Browser-based multi-model code generation and verification. Free & unlimited.

The web platform at respcode.com provides the full RespCode experience in your browser — write prompts, select AI models, choose an architecture, and watch code generate in real time with sandbox verification. The web IDE is completely free with unlimited generations.

Orchestration Modes

RespCode offers three ways to orchestrate AI models:

Supported Architectures

Architecture	Toolchain	Sandbox	Use Case
x86_64	GCC 13, Clang 17	Daytona	Desktop, server, algorithms
ARM64 (AArch64)	aarch64-linux-gnu-gcc	Firecracker on Graviton	Apple Silicon, Raspberry Pi, cloud instances
ARM32 (ARMv7)	arm-linux-gnueabihf-gcc	Firecracker (AArch32 mode)	Embedded Linux, 32-bit SBCs
ARM32 Baremetal	arm-none-eabi-gcc + QEMU	Docker + QEMU emulation	STM32, NXP, Nordic nRF, RP2040, TI firmware
RISC-V Coming Soon	riscv64-linux-gnu-gcc	—	Open ISA development (temporarily disabled)
FPGA / HDL Coming Soon	Icarus Verilog, Verilator	—	Verilog, VHDL design (temporarily disabled)
Python	Python 3.11	Sandboxed interpreter	Scripts, automation, ML

AI Models

11 models available from 5 providers:

Provider	Models
Anthropic	claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5
OpenAI	gpt-5-2, gpt-4o-mini
DeepSeek	deepseek-v3, deepseek-coder
Google	gemini-3-pro, gemini-2-flash
Open Source	llama-4-maverick, qwen-3-32b

Sandbox Execution

Every code generation is compiled and executed in an isolated sandbox. ARM code runs in Firecracker microVMs on Graviton instances; x86 code runs in Daytona containers. The sandbox provides:

• Isolation — each execution runs in its own sandbox, destroyed after completion
• Real hardware — ARM64 code runs on actual Graviton instances, not emulators
• Exit code + stdout — pass/fail verification with full output capture
• Time limits — 30-second default timeout prevents infinite loops
• Artifact storage — compiled binaries (.elf, .bin) stored for agent download and deployment

---

VS Code Extension

Multi-model code generation directly in your editor. Coming Soon

Planned features:

• Inline multi-model code generation
• Side-by-side diff of model outputs
• Sandbox verification results in the editor
• Board selection and deployment from VS Code

---

MCP Server

Connect RespCode to Claude Desktop, Cursor, and MCP clients. Coming Soon

Planned tools:

• generate_code — trigger multi-model generation with architecture targeting
• run_sandbox — compile and execute code in Firecracker microVMs
• list_models — query available models and presets
• deploy_to_board — flash firmware to connected hardware

---

API Reference

The RespCode API powers all clients (web, agent, VS Code, MCP). Base URL: https://respcode.com/api

Endpoint	Method	Description
/user	GET	Get user info, plan, credits
/generate	POST (SSE)	Stream multi-model code generation
/artifacts/{gen_id}	GET	List compiled artifacts
/artifacts/{gen_id}/{art_id}/download	GET	Download binary artifact
/agent/version.json	GET	Check for agent updates

All endpoints require Authorization: Bearer <api_key> header (except version check).

Credits & Pricing

Tier	Credits per generation	Models included
Flagship	29	Claude Opus, GPT-5, Gemini 3 Pro, DeepSeek Coder
Mid	17	Claude Sonnet, GPT-4o, Gemini Flash, DeepSeek V3
Open Source	8	Llama 4, Qwen 3, DeepSeek, Mistral
Budget	6	Claude Haiku, GPT-4o Mini, Gemini Flash

Web platform is free with unlimited generations. Agent & API users get 500 free credits. Upgrade to Pro (29/mo) or Max ($49/mo) for more.