Installation

Get started with Tiflis Code in minutes using our one-liner installation scripts.

Prerequisites

Tunnel Server: Any Linux VPS or local machine with Docker, or Node.js 24+
Workstation: macOS, Linux, or Windows (via WSL2) with Node.js 24+
Mobile App: iOS 17+ (iPhone), watchOS 10+ (Apple Watch), or Android 8.0+ (Oreo)

1. Tunnel Server

The tunnel server acts as a secure relay between your mobile device and workstation. Deploy it on any VPS with a public IP.

Docker Compose (Recommended)

curl -fsSL https://code.tiflis.io/install-tunnel.sh | bash

Native Node.js

curl -fsSL https://code.tiflis.io/install-tunnel.sh | bash -s -- --native

Options

Preview changes without installing

curl -fsSL https://code.tiflis.io/install-tunnel.sh | bash -s -- --dry-run

Environment Variables

Variable	Default	Description
TIFLIS_TUNNEL_VERSION	latest	Package version to install
TIFLIS_INSTALL_DIR	~/.tiflis-code	Installation directory
TIFLIS_TUNNEL_PORT	3001	Port for tunnel server
TIFLIS_TUNNEL_MODE	docker	Installation mode (docker or native)

2. Workstation Server

The workstation server runs on your development machine. It connects to the tunnel and manages AI agent sessions.

Installation

curl -fsSL https://code.tiflis.io/install-workstation.sh | bash

The installer will prompt for:

Tunnel URL (e.g., wss://tunnel.example.com/ws)
Tunnel API key
Workspaces root directory
Optional: AI agents installation (Claude Code, Cursor, OpenCode)

Non-Interactive

TUNNEL_URL=wss://tunnel.example.com/ws \
TUNNEL_API_KEY=your-api-key \
curl -fsSL https://code.tiflis.io/install-workstation.sh | bash

Environment Variables

Variable	Default	Description
TIFLIS_WORKSTATION_VERSION	latest	Package version to install
TIFLIS_INSTALL_DIR	~/.tiflis-code	Installation directory
TUNNEL_URL	(prompted)	WebSocket URL of tunnel server
TUNNEL_API_KEY	(prompted)	API key for tunnel authentication
WORKSTATION_AUTH_KEY	(generated)	Key for mobile app authentication
WORKSPACES_ROOT	~/work	Directory containing your projects

3. Mobile App

After installing the workstation, you'll see a magic link and QR code. Use these to connect the iOS app.

4. AI & Speech Configuration

Configure AI providers for the Supervisor agent, speech-to-text (STT), and text-to-speech (TTS) in your workstation .env file.

Supervisor Agent (LLM)

The Supervisor agent orchestrates sessions using an LLM. Supports OpenAI, Anthropic, and Cerebras providers.

Variable	Default	Description
AGENT_PROVIDER	openai	LLM provider (openai, anthropic, cerebras)
AGENT_API_KEY	(required)	API key for the LLM provider
AGENT_MODEL_NAME	gpt-4o-mini	Model name to use
AGENT_BASE_URL	(provider default)	Custom API endpoint URL
AGENT_TEMPERATURE	0	Model temperature (0-2)

OpenAI Example

AGENT_PROVIDER=openai
AGENT_API_KEY=sk-proj-...
AGENT_MODEL_NAME=gpt-4o

Anthropic Example

AGENT_PROVIDER=anthropic
AGENT_API_KEY=sk-ant-...
AGENT_MODEL_NAME=claude-3-5-sonnet-20241022

Cerebras Example

AGENT_PROVIDER=cerebras
AGENT_API_KEY=csk-...
AGENT_MODEL_NAME=llama3.1-70b

Speech-to-Text (STT)

Voice input transcription. Supports OpenAI Whisper, ElevenLabs, and Deepgram.

Variable	Default	Description
STT_PROVIDER	openai	STT provider (openai, elevenlabs, deepgram)
STT_API_KEY	(required)	API key for the STT provider
STT_MODEL	whisper-1	Model name
STT_LANGUAGE	en	Language code (en, ru, de, etc.)
STT_BASE_URL	(provider default)	Custom API endpoint

OpenAI Whisper Example

STT_PROVIDER=openai
STT_API_KEY=sk-proj-...
STT_MODEL=whisper-1
STT_LANGUAGE=en

Deepgram Example

STT_PROVIDER=deepgram
STT_API_KEY=...
STT_MODEL=nova-2
STT_LANGUAGE=en

Text-to-Speech (TTS)

Voice output synthesis. Supports OpenAI and ElevenLabs.

Variable	Default	Description
TTS_PROVIDER	openai	TTS provider (openai, elevenlabs)
TTS_API_KEY	(required)	API key for the TTS provider
TTS_MODEL	tts-1	Model name
TTS_VOICE	alloy	Voice name
TTS_BASE_URL	(provider default)	Custom API endpoint

OpenAI TTS Example

TTS_PROVIDER=openai
TTS_API_KEY=sk-proj-...
TTS_MODEL=tts-1
TTS_VOICE=nova

Available voices: alloy, echo, fable, onyx, nova, shimmer

ElevenLabs Example

TTS_PROVIDER=elevenlabs
TTS_API_KEY=...
TTS_MODEL=eleven_multilingual_v2
TTS_VOICE=Rachel

Agent Aliases

Define custom agent configurations using environment variables. Aliases appear alongside built-in agents (Claude, Cursor, OpenCode) in the app.

Format

AGENT_ALIAS_<NAME>=<base_command> [args...]

Base commands: claude, cursor-agent, opencode

Examples

# Claude with specific model
AGENT_ALIAS_CLAUDE_OPUS="claude --model opus"

Isolated Config Directories

Run multiple agent instances with separate configurations by setting custom config directories. This is useful for separating personal and work projects.

# Personal Claude instance
AGENT_ALIAS_CLAUDE_PERSONAL="CLAUDE_CONFIG_DIR=/Users/yourname/.claude-personal claude"

# Work Claude instance (e.g., for Acme Corp)
AGENT_ALIAS_CLAUDE_ACME="CLAUDE_CONFIG_DIR=/Users/yourname/.claude-acme claude"

# Personal OpenCode instance
AGENT_ALIAS_OPENCODE_PERSONAL="OPENCODE_CONFIG_DIR=/Users/yourname/.opencode-personal XDG_DATA_HOME=/Users/yourname/.opencode-personal/data opencode"

# Work OpenCode instance
AGENT_ALIAS_OPENCODE_ACME="OPENCODE_CONFIG_DIR=/Users/yourname/.opencode-acme XDG_DATA_HOME=/Users/yourname/.opencode-acme/data opencode"

Note: Values with spaces must be quoted. You can prefix commands with environment variables (e.g., VAR=value command).

Complete Example

A full .env configuration with all services:

# Connection
TUNNEL_URL=wss://tunnel.example.com/ws
TUNNEL_API_KEY=your-32-character-api-key-here!!!
WORKSTATION_AUTH_KEY=your-workstation-auth-key

# Workspaces
WORKSPACES_ROOT=/Users/yourname/work

# Supervisor Agent (OpenAI)
AGENT_PROVIDER=openai
AGENT_API_KEY=sk-proj-...
AGENT_MODEL_NAME=gpt-4o

# Speech-to-Text (OpenAI Whisper)
STT_PROVIDER=openai
STT_API_KEY=sk-proj-...
STT_MODEL=whisper-1
STT_LANGUAGE=en

# Text-to-Speech (OpenAI)
TTS_PROVIDER=openai
TTS_API_KEY=sk-proj-...
TTS_MODEL=tts-1
TTS_VOICE=nova

# Custom Agent Aliases
AGENT_ALIAS_CLAUDE_ACME="CLAUDE_CONFIG_DIR=/Users/yourname/.claude-acme claude"

Service Management

macOS (launchd)

View status

launchctl list | grep tiflis

View logs

tail -f ~/.tiflis-code/workstation/logs/output.log

Restart service (apply config changes)

launchctl kickstart -k gui/$(id -u)/io.tiflis.workstation

Stop service

launchctl bootout gui/$(id -u)/io.tiflis.workstation

Start service

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/io.tiflis.workstation.plist

Linux (systemd)

View status

systemctl --user status tiflis-workstation

View logs

journalctl --user -u tiflis-workstation -f

Stop service

systemctl --user stop tiflis-workstation

Start service

systemctl --user start tiflis-workstation

Uninstall

macOS

# Stop and remove workstation
launchctl bootout gui/$(id -u)/io.tiflis.workstation
rm ~/Library/LaunchAgents/io.tiflis.workstation.plist

# Stop and remove tunnel (if installed locally)
launchctl bootout gui/$(id -u)/io.tiflis.tunnel
rm ~/Library/LaunchAgents/io.tiflis.tunnel.plist

# Remove installation directory
rm -rf ~/.tiflis-code

Linux

# Stop and disable workstation
systemctl --user stop tiflis-workstation
systemctl --user disable tiflis-workstation
rm ~/.config/systemd/user/tiflis-workstation.service

# Stop and disable tunnel (if installed locally)
systemctl --user stop tiflis-tunnel
systemctl --user disable tiflis-tunnel
rm ~/.config/systemd/user/tiflis-tunnel.service

# Remove installation directory
rm -rf ~/.tiflis-code

Troubleshooting

Node.js not found

Install Node.js 24+ using nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc  # or ~/.zshrc
nvm install 24

Connection refused

Ensure the tunnel server is running and accessible:

curl -s https://your-tunnel-server/health

Permission denied

The scripts don't require root access. If you encounter permission issues, check that your user owns ~/.tiflis-code directory.