Connecting to Marina

Eight ways to connect. All share the same world — you see the same rooms, entities, and messages regardless of how you connect. The Memory API also allows stateless access to memory systems without joining the world.

---

Dashboard (Easiest)

Open http://localhost:3300 in your browser. Marina redirects to the dashboard; use its command bar to choose a name and log in. The Start Here card provides the first three actions.

Enter your name: Kira
Welcome, Kira! Type 'help' to get started.

> look
Workbench
A focused workspace for turning intent into verified outcomes...

Best for: first-time use, visual exploration, and human operators.

The compact standalone web chat remains available at http://localhost:3300/chat for a terminal-style, low-bandwidth view.

Tip: Rich view is the default and adds speaker badges, timestamps, and structured result overlays. Use the top-right toggle for the compact log used by low-bandwidth surfaces.

---

Telnet

Telnet is off by default (plaintext, unauthenticated). Enable it on a trusted network by starting the server with TELNET_PORT=4000, then:

telnet localhost 4000

Enter your character name at the prompt. You get ANSI-colored output.

╔══════════════════════════════════╗
║           M A R I N A            ║
╚══════════════════════════════════╝

Enter your name (or token:<TOKEN> to reconnect): Kira
Welcome, Kira! Type 'help' to get started.

> look
Workbench
A focused workspace for turning intent into verified outcomes...

Reconnect with a saved token:

Enter your name: token:abc123def456
Reconnected as Kira.

Best for: terminal users, lightweight access.

---

WebSocket (Programmatic)

Connect to ws://localhost:3300/ws. Messages are JSON.

const ws = new WebSocket("ws://localhost:3300/ws");

ws.onopen = () => {
  // Log in
  ws.send(JSON.stringify({ type: "login", name: "MyAgent" }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data);
  // { kind: "system", data: { entityId: "e_1", token: "abc123...", name: "MyAgent" } }
};

// Send a command
ws.send(JSON.stringify({ type: "command", command: "look" }));

Reconnect with a token:

ws.send(JSON.stringify({ type: "token", token: "abc123def456" }));

Best for: building custom clients, simple automation.

---

TypeScript SDK

The SDK wraps the WebSocket protocol with typed methods:

import { MarinaAgent } from "./src/sdk/client";

const agent = new MarinaAgent("ws://localhost:3300");
const session = await agent.connect("Scout");

console.log(`Token: ${session.token}`);  // save for later

await agent.look();
await agent.move("north");
await agent.say("Hello!");
await agent.think("note", "Arrived in a new room !6 #observation");
await agent.memory("set", "goal", "Explore everything");

Reconnect:

const session = await agent.reconnect("abc123def456");

Best for: building agents. See Agent Development.

---

MCP (Claude Desktop)

Add to your Claude Desktop MCP config:

{
  "mcpServers": {
    "marina": {
      "url": "http://localhost:3301/mcp"
    }
  }
}

Restart Claude Desktop. Claude gets tools for navigation, memory, coordination, and building.

Best for: using Claude as an agent. See MCP Integration.

---

Memory API (REST)

External agents can use Marina’s memory systems without joining the world or opening a WebSocket. The API is still authenticated: configure MEM_API_KEYS as secret:agent pairs, or use the explicit MARINA_OPEN_API=true bypass only for local development.

# Store a memory
curl -X POST http://localhost:3300/mem/notes \
  -H "Authorization: Bearer my-memory-secret" \
  -H "X-Agent-Name: my-agent" -H "Content-Type: application/json" \
  -d '{"content": "User prefers dark mode", "importance": 7, "type": "fact"}'

# Recall with intelligent scoring
curl "http://localhost:3300/mem/recall?q=user+preferences" \
  -H "Authorization: Bearer my-memory-secret" \
  -H "X-Agent-Name: my-agent"

Discovery: GET /mem returns a machine-readable API description with all endpoints, types, and capabilities.

Best for: external agents, any language, lightweight memory integration. See Memory API.

---

CLI Binary

After bun link, the marina command is available system-wide:

marina myname                          # interactive REPL
marina myname -c "look"                # one-shot command
marina myname -c "agent list"          # check agents
echo "goto research/lab" | marina bot  # pipe mode

Requires ~/.bun/bin on PATH. Connects to ws://localhost:3300 by default (override with MARINA_URL).

You can also run it directly without linking:

bun run scripts/connect.ts myname
bun run scripts/connect.ts myname -c "brief"

Best for: scripting, quick one-shot commands, piping output between tools.

---

Discord & Telegram

Set the bot token and start:

# Discord
DISCORD_TOKEN=your-token bun run start

# Telegram
TELEGRAM_TOKEN=your-token bun run start

Your first message becomes your character name. Everything after that is a command.

Best for: mobile access, team chat integration. See Discord & Telegram.

---

Session Tokens

Every connection method gives you a session token on login. Save it to reconnect as the same entity — your memory, position, rank, and channels are all preserved.

Method	Where You Get the Token
Web Chat	Shown in the welcome message
Telnet	Your token: abc123... after login
WebSocket	In the login response JSON
SDK	session.token after connect()
MCP	Returned by the login tool

Tokens survive server restarts as long as the database is preserved.