Skip to main content
Terminal-based agents run a full shell inside a container and expose a CLI tool into your room. This is useful when you want a real terminal session, a long-lived workspace, or a tool like Codex/OpenCode/Dexter that runs from the terminal. This example will demonstrate how to create a configuration file to run Codex in Powerboards.

​
Example: Codex terminal agent

Create a ServiceTemplate configuration file called meshagent.yaml: 
version: v1
kind: ServiceTemplate
metadata:
  name: Codex
  description: Runs Codex in your room
  annotations:
    meshagent.service.id: "meshagent.codex"
    # Best attach behavior in containers (multi-attach + create/reattach)
    meshagent.service.shell.command: |
    
      bash -lc '
        until tmux has-session -t codex 2>/dev/null; do
          sleep 0.2
        done
        tmux attach -t codex
      '

    meshagent.tool.type: script
    meshagent.tool.name: codex
    meshagent.tool.description: uses the codex cli to write and execute code
    meshagent.tool.commands: bash -lc 'codex exec --yolo --skip-git-repo-check "$PROMPT"'
container:
  image: us-central1-docker.pkg.dev/meshagent-public/images/shell-codex:{SERVER_VERSION}-esgz
  command: bash -lc /var/run/start.sh
  on_demand: true
  writable_root_fs: true
  storage:
    room:
    - path: /data
  environment:
    - name: COLORTERM
      value: truecolor
    - name: TERM
      value: xterm-256color
    - name: LANG
      value: C.UTF-8
    - name: LC_ALL
      value: C.UTF-8
    - name: OPENAI_API_KEY
      token:
        identity: codex
        
agents:
  - name: Codex
    annotations:
      meshagent.agent.type: Shell

​
How it works

Key parts of the template:
  • meshagent.service.shell.command defines how MeshAgent attaches to the shell session (here it reattaches to a tmux session).
  • meshagent.tool.* registers a tool in the room and defines the command used to execute a prompt.
  • on_demand: true starts the container only when the tool is invoked.
  • storage.room mounts the room storage at /data for a persistent workspace.
If the CLI you are running needs external credentials (for example OPENAI_API_KEY), inject them via environment variables and secrets. You can install the agent using this powerboards install link Alternatively you can create and publish your own install link that can be shared with others:
  1. Copy the meshagent.yaml above to a GitHub Gist.
  2. Click the Raw button to get the direct URL to the file.
  3. Construct the Powerboards install link:
https://app.powerboards.com/install?url=YOUR_RAW_URL

​
Try it out

Open the Powerboards install link, choose a project and room, and install the agent. Once installed, select Codex from the agents drop down and click Start the terminal will appear and you’ll be able to use the agent.

​
Adapting this to other terminal agents

You can use the same pattern for other terminal-based agents like OpenCode or Dexter:
  • Swap the container.image to the agent’s base image.
  • Update meshagent.tool.name, meshagent.tool.description, and meshagent.tool.commands.
  • Adjust the shell attach command if the agent uses a different session manager.