Skip to content
Hoard Hoard

Codex Setup

This guide covers connecting Codex to Hoard.

Quick Setup

  1. Ensure Hoard server is running

    Terminal window
    hoard serve

  2. Run the setup command

    Terminal window
    hoard setup --codex

  3. Set the environment variable

    Add to ~/.zshrc or ~/.bashrc:

    Terminal window
    export HOARD_TOKEN="hoard_sk_544e528b4b1ae6..."

  4. Restart terminal and Codex

  5. Test the connection In Codex, run /mcp to list connected servers

Remote Hoard Server

If Hoard runs on another machine:

Terminal window
hoard setup remote --url https://hoard.example.com --token hoard_sk_... --codex

Automation flow (advanced):

Terminal window
hoard setup remote --url https://hoard.example.com --admin-token YOUR_ADMIN_SECRET --codex

Instruction Injection

Hoard can inject a short guidance block into AGENTS.md so Codex agents consistently use:

  • memory_write for stable facts/preferences
  • inbox_put for durable notes/documents
  • sync when file changes are not visible yet

Manual control:

Terminal window
hoard instructions --codex --dry-run
hoard instructions --codex --yes

Configuration

Hoard creates ~/.codex/config.toml:

[mcp_servers.hoard]
url = "http://127.0.0.1:19850/mcp"
bearer_token_env_var = "HOARD_TOKEN"

Troubleshooting

”HOARD_TOKEN not set” error

Ensure the environment variable is exported:

Terminal window
echo $HOARD_TOKEN

Server not appearing in /mcp

  1. Check config exists: cat ~/.codex/config.toml
  2. Verify URL is correct
  3. Restart Codex

Connection errors

  1. Ensure Hoard server is running: hoard serve --status
  2. Check the port (default 19850)

Next Steps