Skip to main content

Contributing

Thank you for your interest in contributing to aibox!

Getting Started​

  1. Fork and clone the repository:

    git clone https://github.com/projectious-work/aibox.git
    cd aibox

  2. Start the development container:

    cd .devcontainer
    docker compose up -d
    docker compose exec aibox bash

    Or open in VS Code with the Dev Containers extension.

  3. Build the CLI:

    cd cli
    cargo build

  4. Run the tests:

    cargo test
    cargo clippy -- -D warnings
    cargo fmt -- --check

Project Structure​

  • cli/ — Rust CLI source code
  • images/ — Published container image Dockerfiles
  • addons/ — Addon definitions (language runtimes, tool bundles, AI agents)
  • docs-site/ — Docusaurus documentation source
  • .devcontainer/ — This project's own dev environment

Process content (skills, packages, primitives, processes, the canonical AGENTS.md) lives in processkit, not in this repository. As of v0.16.0 aibox no longer ships a templates/ directory or a schemas/ directory — both have moved upstream to processkit.

See CLAUDE.md for detailed architecture notes.

Development Workflow​

CLI Changes​

  1. Make your changes in cli/src/
  2. Run cargo test to verify all tests pass
  3. Run cargo clippy -- -D warnings for lint checks
  4. Run cargo fmt to format code

Image Changes​

  1. Edit the relevant Dockerfile in images/
  2. Build locally to verify: docker build -t aibox-test images/<flavor>/
  3. Test that derived images still build if you changed the base

Documentation Changes​

  1. Edit or add pages in docs-site/docs/
  2. Update docs-site/sidebars.js if adding new pages
  3. Preview locally: cd docs-site && npm run start

Pull Requests​

  • Keep PRs focused on a single change
  • Include a clear description of what and why
  • Ensure all tests pass and clippy is clean
  • Update documentation if your change affects user-facing behavior

Reporting Issues​

File issues at github.com/projectious-work/aibox/issues.

When filing an issue, please:

  • Use a descriptive title
  • Label it: bug for broken behavior, enhancement for feature requests, documentation for doc gaps
  • Include steps to reproduce (for bugs) or a use case description (for enhancements)
  • Mention the aibox version (aibox --version) and container image flavor if relevant