https://github.com/achuthanmukundan00/suitcase
Your personal AI career companion.
https://github.com/achuthanmukundan00/suitcase
ai automation career fastapi job-search nlp python
Last synced: 3 days ago
JSON representation
Your personal AI career companion.
- Host: GitHub
- URL: https://github.com/achuthanmukundan00/suitcase
- Owner: achuthanmukundan00
- License: mit
- Created: 2026-04-18T15:19:28.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-07T03:21:34.000Z (18 days ago)
- Last Synced: 2026-06-07T03:29:56.828Z (18 days ago)
- Topics: ai, automation, career, fastapi, job-search, nlp, python
- Language: Python
- Homepage: https://suitcase-docs.pages.dev/
- Size: 5.87 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Suitcase
Your private AI career copilot. Pack your career proof, run job-search campaigns, prepare tailored applications, and chat with your agent — all from your phone or your browser.
**No cloud dependency. Bring your own LLM. Your data stays local.**
---
## Quickstart
```bash
# 1. Prerequisites: Docker + docker compose plugin + git
# https://docs.docker.com/engine/install/
# 2. One-command install (recommended)
curl -fsSL https://raw.githubusercontent.com/achuthanmukundan00/Suitcase/main/scripts/install.sh | bash
# Or clone manually:
# git clone https://github.com/achuthanmukundan00/Suitcase.git
# cd Suitcase && ./scripts/install.sh
# 3. Edit .env and set LLM_API_KEY
# 4. Open
open http://localhost:8000/app
```
> The installer clones the repo, builds the frontend, creates `.env`, and starts Docker with the full runtime profile by default. Use `./scripts/install.sh --lite` to skip the full runtime.
Then complete setup in the app at `/setup`.
### Self-Updating
Suitcase can check for and request its own updates. From chat, the agent can notify you when a new version is available:
```bash
./scripts/update.sh # git pull → rebuild → restart
./scripts/update.sh --check # check for updates only
```
The agent's `self_update` tool handles this from inside the conversation — Suitcase says "I'll be right back" and you run the command.
## Powers And Skills
Suitcase uses two layers:
- `Powers`: user-facing setup permissions and configuration. A power answers: can Suitcase use this capability in the container, and what is missing?
- `Skills`: runtime tool implementations. A power enables one or more skills.
Examples:
- `browser` power enables browser skills like `browser.check_page`
- `github` power enables GitHub skills like `github.search`
- `documents` power enables document extraction/conversion skills
Setup now includes:
- power diagnostics: exact missing binaries, env names, auth hints, and install commands
- runtime skills visibility: which skills are callable right now
- confirmation policy: side-effect skills require explicit confirmation before execution
## Full Powers Install Path
The installer and `./start.sh` start the full runtime profile by default so Docker-backed tool execution, Bun, and the Synax bridge are available during setup. If you start Compose manually, use:
```bash
docker compose --profile runtime-full up --build -d suitcase-runtime-full
```
This installs the common package-backed dependencies for powers and skills, including:
- `gh`
- `rclone`
- `ffmpeg`
- `sox`
- `pandoc`
- `poppler-utils`
- `tesseract-ocr`
- `ocrmypdf`
- `imagemagick`
- `restic`
- `ripgrep`
It also tries to install `aubio-tools` when available on the base image.
Stripe CLI is still documented/manual rather than baked into the image by default.
### How setup works now
Suitcase setup is now **birth-first**:
1. Start the app.
2. Open `/setup`.
3. Complete required birth steps:
- Upload resume
- Configure + verify LLM endpoint
4. Enter Admin.
5. First chat triggers Suitcase first-contact ("born").
6. Add optional integrations later (GitHub, LinkedIn, Discord, Pulse).
## What Suitcase Does
- **Builds your career profile** from your resume, GitHub, LinkedIn, and guided discovery questions
- **Chats with you** through the web UI or Discord — it knows your skills, projects, and goals
- **Scores and tracks job leads** — no auto-submission, everything is review-gated
- **Generates tailored materials** — resumes, cover letters, fit assessments
- **Reflects and grows** — Suitcase has a personality, a self-model, and a soul that evolves
## LLM Setup
Use the Setup UI (`/setup` → "Configure LLM endpoint"). This persists config server-side and verifies connectivity.
### Recommendation
For most users, use a **cloud provider first** (OpenAI/Anthropic class endpoints). They are currently the safer default for instruction-following reliability and boundary adherence.
**LM Studio (local, free)**
```bash
LLM_PROVIDER=local_openai_compatible
LLM_BASE_URL=http://127.0.0.1:1234/v1
LLM_MODEL=qwen3-coder-30b
```
**Ollama**
```bash
LLM_BASE_URL=http://127.0.0.1:11434/v1
LLM_MODEL=qwen3:30b
```
**OpenAI**
```bash
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o-mini
LLM_API_KEY=sk-...
```
> **Model recommendation**: Use at least 8B parameters. The smallest model verified is **Gemma 4 26B MoE (IQ4_XS)** via LM Studio. Smaller models may struggle with instruction following.
>
> **Safety note**: Local models vary heavily in alignment behavior. Use local inference only if you understand the risk tradeoff; a safety-aligned baseline such as Gemma 4 26B is strongly preferred.
## Optional: Runtime Sandbox
For browser automation and tool execution in a sandboxed container:
```bash
docker compose --profile runtime up -d suitcase-runtime
```
`GITHUB_TOKEN` is only needed for this runtime profile build (private Synax SDK dependency).
For a smaller local tool surface:
```bash
./start.sh --lite
```
The install script used by that profile is [scripts/install_full_powers.sh](/home/achu/workspace/git/suitcase/scripts/install_full_powers.sh).
## Optional: Relay (LLM Gateway)
For local model servers that need request routing:
```bash
docker compose --profile relay up -d relay
```
## Optional Integrations
**GitHub** — scan your repos for career evidence:
```bash
GITHUB_TOKEN=github_pat_...
```
**Discord** — chat with Suitcase through DMs:
```bash
DISCORD_ENABLED=true
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_TARGET_USER_ID=your-user-id
```
**Telegram** — chat with Suitcase through Telegram:
```bash
SUITCASE_TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_ALLOWED_USER_IDS=your-user-id
```
## Security
- **No auto-submission** — all external actions require explicit approval
- **Sandboxed execution** — tools run in isolated Docker containers
- **API keys stored server-side** — never exposed to the browser
- **Proposal-only architecture** — Suitcase proposes changes, you approve them
- **Confirmation policy for live skills** — side-effect runtime skills require explicit confirmation before execution
### Security Audit
Run the security audit before exposing Suitcase beyond loopback:
```bash
./scripts/security_audit.sh # baseline
./scripts/security_audit.sh --deep # deep scan
./scripts/security_audit.sh --fix # auto-fix permissions
./scripts/security_audit.sh --deep --fix # full audit + fix
```
### Safety Checklist
- Access the web service only through `localhost` or an SSH tunnel.
- Use the Docker execution backend (default): `SUITCASE_EXECUTION_BACKEND=docker`.
- Do not mount the Docker socket into Suitcase containers.
- Do not mount `/`, `/home`, `~/.ssh`, cloud credential directories.
- Use scoped, disposable API keys.
## Configuration
Primary config is via `.env`, plus Setup UI writes for secrets and LLM settings.
For packaged deployments, TOML templates are under `packaging/config/`.
## Development
```bash
# Frontend dev server (hot reload on :5173)
cd frontend && npm install && npm run dev
# Build frontend for Docker
cd frontend && npm install && npm run build
# Python tests
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python3 -m unittest discover -s tests -v
```
## License
[MIT](LICENSE) © 2026 Achuthan Mukundan