# acoj-sandbox

**Repository Path**: jiangbyte/acoj-sandbox

## Basic Information

- **Project Name**: acoj-sandbox
- **Description**: ACOJ 的判题沙箱项目，为在线判题 worker 提供可集成、可验证、可扩展的本地执行沙箱
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-13
- **Last Updated**: 2026-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# acoj-sandbox

Linux 判题沙箱：C++ 引擎 `acosandbox` + Python 包 `acoj_sandbox`。  
职责：编译与运行用户程序、资源限制、隔离（namespaces / cgroup / seccomp / rootfs）。

任务队列与 OJ 计分由 [`acoj-worker`](https://github.com/jiangbyte/acoj-worker) 承担。

## 原理

```text
调用方 (Python)
  → SandboxClient / SandboxWorkerPool
  → acosandbox (JSON / worker JSONL)
  → fork + rlimit [+ seccomp] [+ namespaces] [+ cgroup] [+ rootfs]
  → 编译器 / 用户程序 / checker
```

| 组件 | 作用 |
|------|------|
| `src/` → `build/acosandbox` | 执行与计量 |
| `python/acoj_sandbox/` | 客户端、语言配置、进程池 |
| `lang/` → `acoj-sandbox-lang` | `LanguageId`（可单独 `pip install`） |

语言 argv 由调用方 `LanguagesConfig` 提供。状态：`AC` `CE` `RE` `TLE` `MLE` `OLE` `SE` `IE` 等；`WA` 由 checker 或上层比对给出。

Java / Go：语言规格使用 `memory_limit_check_only=True`；大链接产物提高 `output_bytes`。

## 隔离

| 项 | 说明 |
|----|------|
| `enable_namespaces` | mount / net / ipc / uts |
| `rootfs_path` + `bind_mounts` | 最小根与系统路径（如 `/usr` `/etc` `/proc`） |
| `use_pivot_root` | 默认开启；put_old 为 `.old_root.<pid>` |
| `CgroupConfig` | memory / pids；默认 base `/sys/fs/cgroup/acoj-sandbox` |

Docker：`--privileged --cgroupns=host`。详见 `python/acoj_sandbox/client.py`。

## 依赖

Linux、C++20、`libseccomp`、Python ≥ 3.10、目标语言工具链。

```bash
sudo apt-get install -y build-essential pkg-config libseccomp-dev python3 python3-pip
```

## 构建与安装

```bash
make
ACOJ_SANDBOX_SKIP_NATIVE_BUILD=1 pip install .
pip install -e ./lang && ACOJ_SANDBOX_SKIP_NATIVE_BUILD=1 pip install -e .
```

二进制：`ACOJ_SANDBOX_BINARY` → 包内路径 → `build/acosandbox`。

```bash
pip install ./lang
# from acoj_sandbox_lang import LanguageId
```

## 用法

```python
from acoj_sandbox import (
    SandboxClient, LanguagesConfig, compiled_language, script_language, Status,
)

langs = LanguagesConfig([
    compiled_language(
        id="cpp17",
        compile_argv=["/usr/bin/g++", "-std=c++17", "-O2", "-o", "{exe}", "{source}"],
        run_argv=["{exe}"],
    ),
    script_language(id="python3", argv=["/usr/bin/python3", "{source}"]),
])
client = SandboxClient(languages=langs)
result = client.run_source(
    language="cpp17",
    source='#include <iostream>\nint main(){std::cout<<"ok\\n";}\n',
)
assert result.status == Status.AC
```

批量：`run_cases(..., isolation=..., cgroup=...)`。

```bash
./build/acosandbox self-test
```

## 测试

| 命令 | 说明 |
|------|------|
| `make test` | smoke / 模式 / 短 benchmark |
| `make test-modes` | 判题模式 |
| `make test-python-package` | 安装后验证 |
| `sudo make test-root` | namespaces / cgroup / rootfs |
| `make benchmark` | 性能 |
| `tests/test_concurrent_rootfs_pivot.py` | 共享 rootfs 并发 pivot |

## 目录

```text
src/ include/
python/
lang/
tests/
Makefile
```

worker 镜像通过 BuildKit `--build-context sandbox=…` 编入本仓。见 acoj-worker README。