inkreach-teable-cli/skills/inkreach-teable/guides/instance-access.md

Instance Access

How to reach the deployed inkreach-teable instance, acquire credentials, and verify health. This file describes the reference deployment — adapt endpoint/ports for your own deployment.

Connection

Service	URL / Port	Mode	Purpose
Backend API	http://localhost:3003	production (NODE_ENV=production)	REST API, automation engine, websocket
Frontend	http://localhost:3002	production	End-user web UI (Next.js)
PostgreSQL	localhost:5432	—	Database (db: teable, user: teable)
Redis	localhost:6379	—	BullMQ queue for automation runs, distributed lock

• The frontend reads SOCKET_PORT from .env to point its websocket at the backend — verify it equals the backend port (3003 on this host), not the default 3001.
• End users browse :3002. The backend :3003 is the API only (BACKEND_SKIP_NEXT_START=true disables the embedded Next server).
• ⚠️ Port map differs from upstream Teable docs (:3000) — on this host :3000 is held by an unrelated container (inkreach-web). Always verify with ss -tlnp before assuming.

Health Checks

# Backend API up?
curl -s -o /dev/null -w '%{http_code}' http://localhost:3003/api/auth/signin -X POST \
  -H 'Content-Type: application/json' -d '{}'   # expect 401 (endpoint exists, bad creds)

# Frontend up?
curl -s -o /dev/null -w '%{http_code}' http://localhost:3002   # expect 307 or 200

# Ports listening?
ss -tlnp | grep -E ':3003|:3002|:5432|:6379'

If :3003 is unreachable but systemd shows active, the worker likely OOM-crashed while the pnpm parent stayed alive:

systemctl --user stop teable-backend.service
pkill -9 -f 'dist/index.js'
systemctl --user start teable-backend.service

Acquiring a PAT (Personal Access Token)

The CLI authenticates with a PAT (teable_{id}_{encryptedSign}). Two ways to get one:

Option A — via the CLI (needs a session cookie or existing token)

inkreach-teable auth token create --name my-cli \
  --scopes automation|read,automation|create,automation|update,automation|delete,table|read,record|read,record|create,record|update \
  --base-ids bseXXX --expires 2099-12-31
# → prints full token ONCE

Note: auth token list/create may require a session (browser login) rather than a PAT — if you get 403, use Option B.

Option B — via the web UI (recommended for the first token)

1. Log in to http://localhost:3002 as an admin.
2. User menu → Settings → Personal Access Tokens.
3. Create a token with scopes: automation|*, table|*, record|*, field|*, view|* as needed. Limit to the base if desired.
4. Copy the teable_xxx_yyy string.

Configure the CLI

inkreach-teable auth login --endpoint http://localhost:3003 --token <PAT> --base-id bseXXX
inkreach-teable auth status   # verify

Reference Credentials (local dev)

Never commit real secrets. The reference dev instance uses:

• ⚠️ The old admin account hr_admin@xingchen.tech no longer exists (verified 2026-08). Current users: inkreach@inkreach.pod (admin) — password: ask maintainer, browser login only.
• Throwaway accounts for testing can be created via POST /api/auth/signup (open on this instance).
• Base: bseeZR7yiDNeMPCa4CN (人事薪资管理) — the test base with ~600 automations.
• Test table: tblzPOXQvUruQosKNP5 (has button fields for automation testing).

For CLI use, always prefer a PAT over the admin password.

Permissions

• PAT scope ∩ base role = effective permission. To manage automations you need automation|read/create/update/delete scopes and a role of editor+ on the base.
• Roles: owner (all), creator (all on the base), editor (read/create/update), commenter (read), viewer (read).
• Workflows auto-create an internal token on activation (name workflow:{id}, scope limited to table/record read+write) — used by action nodes, not for CLI auth.

Troubleshooting Access

Symptom	Fix
401 Unauthorized	Token wrong/expired → recreate PAT, auth login again
403 Forbidden	Token lacks scope, or base role too low → widen scopes / raise role
404 Base not found	Wrong base id, or endpoint points to a different instance → auth status, check --base-id
Connection refused	Backend down → health check, restart service (see development.md)