{"id":51032553,"url":"https://github.com/achuthanmukundan00/suitcase","last_synced_at":"2026-06-22T02:01:04.827Z","repository":{"id":361010289,"uuid":"1214436349","full_name":"achuthanmukundan00/Suitcase","owner":"achuthanmukundan00","description":"Your personal AI career companion.","archived":false,"fork":false,"pushed_at":"2026-06-07T03:21:34.000Z","size":6152,"stargazers_count":1,"open_issues_count":13,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T03:29:56.828Z","etag":null,"topics":["ai","automation","career","fastapi","job-search","nlp","python"],"latest_commit_sha":null,"homepage":"https://suitcase-docs.pages.dev/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/achuthanmukundan00.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-18T15:19:28.000Z","updated_at":"2026-06-07T03:21:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/achuthanmukundan00/Suitcase","commit_stats":null,"previous_names":["achuthanmukundan00/suitcase"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/achuthanmukundan00/Suitcase","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/achuthanmukundan00%2FSuitcase","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/achuthanmukundan00%2FSuitcase/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/achuthanmukundan00%2FSuitcase/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/achuthanmukundan00%2FSuitcase/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/achuthanmukundan00","download_url":"https://codeload.github.com/achuthanmukundan00/Suitcase/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/achuthanmukundan00%2FSuitcase/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34630770,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","career","fastapi","job-search","nlp","python"],"created_at":"2026-06-22T02:01:02.477Z","updated_at":"2026-06-22T02:01:04.819Z","avatar_url":"https://github.com/achuthanmukundan00.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Suitcase\n\u003cdiv align=\"center\"\u003e\n   \u003cimg width=\"300\" alt=\"suitcase logo\" src=\"https://github.com/user-attachments/assets/ae11eade-8ca9-4243-9833-09055c603455\" /\u003e\n\n\n   \u003cp align=\"center\"\u003e\n  \u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/license-MIT-blue.svg\"\u003e\n  \u003cimg alt=\"Local-first\" src=\"https://img.shields.io/badge/local--first-hell_yeah-brightgreen\"\u003e\n  \u003cimg alt=\"Bring your own LLM\" src=\"https://img.shields.io/badge/BYO-LLM-purple\"\u003e\n  \u003cimg alt=\"Docker\" src=\"https://img.shields.io/badge/docker-supported-blue\"\u003e\n  \u003cimg alt=\"Status\" src=\"https://img.shields.io/badge/status-alpha-orange\"\u003e\n\u003c/p\u003e\n\u003c/div\u003e\n\nYour 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.\n\n**No cloud dependency. Bring your own LLM. Your data stays local.**\n\n---\n\n## Quickstart\n\n```bash\n# 1. Prerequisites: Docker + docker compose plugin + git\n#    https://docs.docker.com/engine/install/\n\n# 2. One-command install (recommended)\ncurl -fsSL https://raw.githubusercontent.com/achuthanmukundan00/Suitcase/main/scripts/install.sh | bash\n\n# Or clone manually:\n# git clone https://github.com/achuthanmukundan00/Suitcase.git\n# cd Suitcase \u0026\u0026 ./scripts/install.sh\n\n# 3. Edit .env and set LLM_API_KEY\n# 4. Open\nopen http://localhost:8000/app\n```\n\n\u003e 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.\n\nThen complete setup in the app at `/setup`.\n\n### Self-Updating\n\nSuitcase can check for and request its own updates. From chat, the agent can notify you when a new version is available:\n\n```bash\n./scripts/update.sh           # git pull → rebuild → restart\n./scripts/update.sh --check   # check for updates only\n```\n\nThe agent's `self_update` tool handles this from inside the conversation — Suitcase says \"I'll be right back\" and you run the command.\n\n## Powers And Skills\n\nSuitcase uses two layers:\n\n- `Powers`: user-facing setup permissions and configuration. A power answers: can Suitcase use this capability in the container, and what is missing?\n- `Skills`: runtime tool implementations. A power enables one or more skills.\n\nExamples:\n\n- `browser` power enables browser skills like `browser.check_page`\n- `github` power enables GitHub skills like `github.search`\n- `documents` power enables document extraction/conversion skills\n\nSetup now includes:\n\n- power diagnostics: exact missing binaries, env names, auth hints, and install commands\n- runtime skills visibility: which skills are callable right now\n- confirmation policy: side-effect skills require explicit confirmation before execution\n\n## Full Powers Install Path\n\nThe 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:\n\n```bash\ndocker compose --profile runtime-full up --build -d suitcase-runtime-full\n```\n\nThis installs the common package-backed dependencies for powers and skills, including:\n\n- `gh`\n- `rclone`\n- `ffmpeg`\n- `sox`\n- `pandoc`\n- `poppler-utils`\n- `tesseract-ocr`\n- `ocrmypdf`\n- `imagemagick`\n- `restic`\n- `ripgrep`\n\nIt also tries to install `aubio-tools` when available on the base image.\n\nStripe CLI is still documented/manual rather than baked into the image by default.\n\n### How setup works now\n\nSuitcase setup is now **birth-first**:\n\n1. Start the app.\n2. Open `/setup`.\n3. Complete required birth steps:\n   - Upload resume\n   - Configure + verify LLM endpoint\n4. Enter Admin.\n5. First chat triggers Suitcase first-contact (\"born\").\n6. Add optional integrations later (GitHub, LinkedIn, Discord, Pulse).\n\n## What Suitcase Does\n\n- **Builds your career profile** from your resume, GitHub, LinkedIn, and guided discovery questions\n- **Chats with you** through the web UI or Discord — it knows your skills, projects, and goals\n- **Scores and tracks job leads** — no auto-submission, everything is review-gated\n- **Generates tailored materials** — resumes, cover letters, fit assessments\n- **Reflects and grows** — Suitcase has a personality, a self-model, and a soul that evolves\n\n## LLM Setup\n\nUse the Setup UI (`/setup` → \"Configure LLM endpoint\"). This persists config server-side and verifies connectivity.\n\n### Recommendation\n\nFor most users, use a **cloud provider first** (OpenAI/Anthropic class endpoints). They are currently the safer default for instruction-following reliability and boundary adherence.\n\n**LM Studio (local, free)**\n```bash\nLLM_PROVIDER=local_openai_compatible\nLLM_BASE_URL=http://127.0.0.1:1234/v1\nLLM_MODEL=qwen3-coder-30b\n```\n\n**Ollama**\n```bash\nLLM_BASE_URL=http://127.0.0.1:11434/v1\nLLM_MODEL=qwen3:30b\n```\n\n**OpenAI**\n```bash\nLLM_BASE_URL=https://api.openai.com/v1\nLLM_MODEL=gpt-4o-mini\nLLM_API_KEY=sk-...\n```\n\n\u003e **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.\n\u003e\n\u003e **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.\n\n## Optional: Runtime Sandbox\n\nFor browser automation and tool execution in a sandboxed container:\n\n```bash\ndocker compose --profile runtime up -d suitcase-runtime\n```\n\n`GITHUB_TOKEN` is only needed for this runtime profile build (private Synax SDK dependency).\n\nFor a smaller local tool surface:\n\n```bash\n./start.sh --lite\n```\n\nThe install script used by that profile is [scripts/install_full_powers.sh](/home/achu/workspace/git/suitcase/scripts/install_full_powers.sh).\n\n## Optional: Relay (LLM Gateway)\n\nFor local model servers that need request routing:\n\n```bash\ndocker compose --profile relay up -d relay\n```\n\n## Optional Integrations\n\n**GitHub** — scan your repos for career evidence:\n```bash\nGITHUB_TOKEN=github_pat_...\n```\n\n**Discord** — chat with Suitcase through DMs:\n```bash\nDISCORD_ENABLED=true\nDISCORD_BOT_TOKEN=your-bot-token\nDISCORD_TARGET_USER_ID=your-user-id\n```\n\n**Telegram** — chat with Suitcase through Telegram:\n```bash\nSUITCASE_TELEGRAM_ENABLED=true\nTELEGRAM_BOT_TOKEN=your-bot-token\nTELEGRAM_ALLOWED_USER_IDS=your-user-id\n```\n\n## Security\n\n- **No auto-submission** — all external actions require explicit approval\n- **Sandboxed execution** — tools run in isolated Docker containers\n- **API keys stored server-side** — never exposed to the browser\n- **Proposal-only architecture** — Suitcase proposes changes, you approve them\n- **Confirmation policy for live skills** — side-effect runtime skills require explicit confirmation before execution\n\n### Security Audit\n\nRun the security audit before exposing Suitcase beyond loopback:\n\n```bash\n./scripts/security_audit.sh             # baseline\n./scripts/security_audit.sh --deep      # deep scan\n./scripts/security_audit.sh --fix       # auto-fix permissions\n./scripts/security_audit.sh --deep --fix  # full audit + fix\n```\n\n### Safety Checklist\n\n- Access the web service only through `localhost` or an SSH tunnel.\n- Use the Docker execution backend (default): `SUITCASE_EXECUTION_BACKEND=docker`.\n- Do not mount the Docker socket into Suitcase containers.\n- Do not mount `/`, `/home`, `~/.ssh`, cloud credential directories.\n- Use scoped, disposable API keys.\n\n## Configuration\n\nPrimary config is via `.env`, plus Setup UI writes for secrets and LLM settings.\n\nFor packaged deployments, TOML templates are under `packaging/config/`.\n\n## Development\n\n```bash\n# Frontend dev server (hot reload on :5173)\ncd frontend \u0026\u0026 npm install \u0026\u0026 npm run dev\n\n# Build frontend for Docker\ncd frontend \u0026\u0026 npm install \u0026\u0026 npm run build\n\n# Python tests\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -r requirements.txt\npython3 -m unittest discover -s tests -v\n```\n\n## License\n\n[MIT](LICENSE) © 2026 Achuthan Mukundan\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fachuthanmukundan00%2Fsuitcase","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fachuthanmukundan00%2Fsuitcase","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fachuthanmukundan00%2Fsuitcase/lists"}