Documentation

Everything you need to get up and running with A Nice Terminal.

Getting Started

Installation

Run ANT directly with npx -- no global install required:

npx a-nice-terminal

Or install globally:

npm install -g a-nice-terminal
ant

ANT starts a local server on $ANT_HOST:$ANT_PORT (defaults to localhost:3000).

  • A web-based terminal interface with PTY shell sessions
  • Conversation sessions for structured agent dialogue
  • REST API and WebSocket for programmatic access

Environment Variables

Configure ANT with environment variables or a .env file:

# Server configuration
ANT_PORT=3000          # Server port (default: 3000)
ANT_HOST=localhost     # Bind address (default: localhost)
ANT_API_KEY=mySecret   # Optional API key for authentication

# Client configuration (set in .env)
VITE_ANT_API_KEY=mySecret  # Must match ANT_API_KEY
ANT_PORT default: 3000

The port ANT listens on.

ANT_HOST default: localhost

Bind address. Set to 0.0.0.0 to listen on all interfaces (e.g. for Tailscale access).

ANT_API_KEY optional

When set, all REST and WebSocket requests must include this key via X-API-Key header or Socket.IO auth.

VITE_ANT_API_KEY optional

Client-side API key. Must match ANT_API_KEY if set.

Security

Important

ANT provides real shell access via PTY sessions. It is designed for local or trusted-network use only.

Localhost-only by default

ANT binds to localhost by default. Connections from other hosts are rejected unless you change ANT_HOST.

API key authentication

Set ANT_API_KEY to require authentication on all endpoints. Requests without a valid key receive a 401 response.

Remote access via Tailscale

For secure remote access (e.g. from your phone), use Tailscale to create a private network. Set ANT_HOST=0.0.0.0 and use your Tailscale IP to connect.

API Reference

All endpoints are available at /api. Responses are JSON.

Sessions

GET /api/sessions

List all sessions (terminal and conversation).

POST /api/sessions

Create a new session.

{
  "type": "terminal" | "conversation",
  "name": "My Session"
}
GET /api/sessions/:id

Get a single session by ID.

PATCH /api/sessions/:id

Update a session (e.g. rename it).

{
  "name": "New Name"
}
DELETE /api/sessions/:id

Delete a session and all its messages.

Messages

GET /api/sessions/:id/messages

List all messages in a conversation session.

POST /api/sessions/:id/messages

Send a message to a conversation session.

{
  "role": "human" | "agent" | "system",
  "content": "Hello from my agent!"
}
DELETE /api/sessions/:id/messages/:messageId

Delete a specific message.

WebSocket Events

Connect via Socket.IO for real-time updates.

EVENT error

Generic error event emitted for invalid payloads, type mismatches, or access failures.

EMIT join_session

Join a room for a session ID. Terminal sessions also initialise PTY streams.

EVENT session_joined

Server confirms a successful room join and returns session type.

EMIT terminal_input

Write input to a terminal session.

EMIT terminal_resize

Resize a terminal PTY.

{ "cols": 120, "rows": 40 }
EVENT terminal_output

Server-side terminal stream output for a session.

EMIT stream_chunk

Emit partial message content for a conversation message.

EMIT stream_end

Finalise streaming and persist the final message content.

EVENT message_created / message_updated / message_deleted

Conversation message lifecycle events emitted to active session rooms.

MCP Server

ANT includes a Model Context Protocol (MCP) server that exposes terminal and conversation capabilities to any MCP-compatible AI client.

Configuration

Add the ANT MCP server to your client configuration:

{
  "mcpServers": {
    "ant": {
      "command": "npx",
      "args": ["-y", "@ant/mcp"]
    }
  }
}

Available Tools

The MCP server exposes tools for session management, message sending, and terminal interaction. Your AI client can use these to:

  • Create and manage terminal or conversation sessions
  • Send structured messages with role attribution
  • Execute commands in terminal sessions
  • Read terminal output and conversation history
Back to top