Cloud-based virtual teaching lab accessible through Chrome browser.

This repository contains the core LabLink packages, Docker images, and documentation:

• lablink-allocator - VM Allocator Service

  pip install lablink-allocator-service

• lablink-client - Client Service

  pip install lablink-client-service

• lablink-cli - Command-line tool to deploy and manage LabLink infrastructure

  uv tool install lablink-cli

Production images are built from PyPI packages and tagged with specific versions:

• lablink-allocator-image - Allocator service container

  docker pull ghcr.io/talmolab/lablink-allocator-image:0.0.2a0
  docker pull ghcr.io/talmolab/lablink-allocator-image:latest

• lablink-client-base-image - Client service container

  docker pull ghcr.io/talmolab/lablink-client-base-image:0.0.7a0
  docker pull ghcr.io/talmolab/lablink-client-base-image:latest

Available Tags:

• <version> (e.g., 0.0.2a0) - Specific package version (recommended for production)
• latest - Latest stable release
• linux-amd64-latest - Latest for specific platform
• <sha> - Specific git commit
• linux-amd64-test - Development/testing builds

See Docker Image Tags for complete tagging strategy.

• LabLink Docs - Comprehensive documentation
  • Getting Started
  • Configuration
  • API Reference
  • Contributing Guide

# Install
uv tool install lablink-cli

# Interactive configuration wizard (Textual TUI)
lablink configure

# Validate your environment
lablink doctor

# Deploy infrastructure
lablink setup   # one-time GCP/Tailscale bootstrap
lablink deploy  # provision allocator + VMs

# Monitor
lablink status  # check running infrastructure
lablink logs    # live log viewer (Textual TUI)

Contributing to LabLink packages:

# Clone the repository
git clone https://github.com/talmolab/lablink.git
cd lablink

# Install uv (recommended Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Setup allocator service for development
cd packages/allocator
uv sync --extra dev

# Setup client service for development
cd ../client
uv sync --extra dev

See the Contributing Guide for detailed development instructions.

• Full Documentation - Complete guide
• Architecture - System design
• Configuration - Configuration options
• API Reference - Package APIs
• Contributing - Contribution guide

lablink/
├── packages/
│   ├── allocator/                   # Allocator Python package
│   │   ├── src/lablink_allocator/   # Source code
│   │   │   └── terraform/           # Client VM Terraform (part of package)
│   │   ├── tests/                   # Unit tests including Terraform tests
│   │   ├── Dockerfile               # Production image (from PyPI)
│   │   └── Dockerfile.dev           # Development image (local code)
│   ├── client/                      # Client Python package
│   │   ├── src/lablink_client/      # Source code
│   │   ├── tests/                   # Unit tests
│   │   ├── Dockerfile               # Production image (from PyPI)
│   │   └── Dockerfile.dev           # Development image (local code)
│   └── cli/                         # CLI Python package (Typer + Textual)
│       ├── src/lablink_cli/         # Source code (commands, TUI, config)
│       └── tests/                   # Unit tests
├── docs/                            # MkDocs documentation
└── .github/workflows/               # CI/CD workflows
    ├── ci.yml                       # Tests, linting, Docker builds
    ├── publish-pip.yml              # PyPI publishing
    ├── lablink-images.yml           # Docker image builds & pushes
    └── docs.yml                     # Documentation deployment

Note: Infrastructure deployment code (allocator EC2, DNS, etc.) has been moved to lablink-template.

LabLink uses independent versioning for its packages:

• lablink-allocator-service:
• lablink-client-service:
• lablink-cli:

See the Release Process for how releases are managed.

We welcome contributions! Please see:

• Contributing Guide - How to contribute
• Developer Guide (CLAUDE.md) - Developer-focused overview
• Code of Conduct - Community guidelines

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make changes and add tests
4. Run tests: cd packages/allocator && uv run pytest
5. Commit: git commit -m "feat: add my feature"
6. Push and open a Pull Request

• LabLink Template - Infrastructure deployment template using LabLink packages

BSD-2-Clause License

LabLink is developed by the Talmo Lab for the research community.

Questions? Check the FAQ or open an issue.