vasted 0.1.0__tar.gz

vasted-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: Report incorrect behavior or regressions
+title: "[bug] "
+labels: bug
+assignees: ""
+---
+
+## Description
+
+What happened?
+
+## Reproduction
+
+Exact commands and steps:
+
+1. 
+2. 
+3. 
+
+## Expected behavior
+
+What did you expect to happen?
+
+## Environment
+
+- OS:
+- Python version:
+- `uv` version:
+- `vasted` version/commit:
+
+## Logs
+
+Paste relevant logs/tracebacks (redact secrets).

vasted-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability report
+    url: https://github.com/borb/vasted/security/advisories/new
+    about: Report security issues privately.

vasted-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Propose a new capability or UX improvement
+title: "[feature] "
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What problem are you trying to solve?
+
+## Proposed solution
+
+Describe your preferred solution.
+
+## Alternatives considered
+
+What else did you consider?
+
+## Additional context
+
+Anything else (examples, links, prior art).

vasted-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,17 @@
+## Summary
+
+Describe what this PR changes and why.
+
+## Changes
+
+- 
+
+## Validation
+
+- [ ] `uv run ruff check .`
+- [ ] `uv run mypy app tests`
+- [ ] `uv run pytest -q`
+
+## Notes
+
+Any migration, compatibility, or operational notes.

vasted-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - name: Sync deps
+        run: uv sync --extra dev
+      - name: Ruff
+        run: uv run ruff check .
+      - name: Mypy
+        run: uv run mypy app tests bot.py
+      - name: Pytest
+        run: uv run pytest -q

vasted-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,64 @@
+name: publish-package
+
+on:
+  workflow_dispatch:
+    inputs:
+      repository:
+        description: "Target repository"
+        required: true
+        type: choice
+        options:
+          - testpypi
+          - pypi
+        default: testpypi
+      publish:
+        description: "Actually publish package"
+        required: true
+        type: boolean
+        default: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - name: Build package
+        run: uv build
+      - name: Validate metadata
+        run: uvx twine check dist/*
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish-testpypi:
+    if: ${{ inputs.publish && inputs.repository == 'testpypi' }}
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment: testpypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    if: ${{ inputs.publish && inputs.repository == 'pypi' }}
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

vasted-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+.venv/
+.env
+*.log
+.DS_Store
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.uv-cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/

vasted-0.1.0/AGENTS.md

@@ -0,0 +1,66 @@
+# AGENTS.md
+
+Guidance for automation agents operating this repository.
+
+## Goal
+
+Run `vasted` commands in fully unattended mode without hanging on interactive prompts.
+
+## Non-Interactive Command Patterns
+
+Use these command forms for automation:
+
+```bash
+# 1) Configure without wizard prompts
+uv run vasted setup --non-interactive \
+  --vast-api-key "$VASTED_API_KEY" \
+  --bearer-token "$VASTED_BEARER_TOKEN" \
+  --client openclaw \
+  --deployment-mode local_pc \
+  --model qwen3-coder-30b \
+  --quality balanced \
+  --gpu-mode auto
+```
+
+```bash
+# 2) Launch worker without confirmation prompts
+uv run vasted up --non-interactive --yes --jinja --model qwen3-coder-30b --quality balanced --gpu-mode auto --no-serve
+```
+
+```bash
+# 3) Poll status/usage
+uv run vasted status --verbose
+uv run vasted usage
+```
+
+```bash
+# 4) Teardown safely for automation
+uv run vasted down --force
+```
+
+## Important Behavior
+
+- `vasted setup --non-interactive` never opens the interactive setup wizard.
+- `vasted up --non-interactive` will fail if a confirmation is needed (for example budget overage).
+- Add `--yes` to `vasted up` to auto-confirm and avoid failures in unattended jobs.
+- `--client openclaw|opencode|custom` sets persisted defaults for jinja template behavior.
+- For OpenClaw/chat-agent use cases, keep `--jinja` enabled (default).
+- For raw completion-style workloads, pass `--no-jinja` if needed.
+- Prefer `--no-serve` in headless environments where proxy process management is external.
+
+## Required Environment Variables
+
+- `VASTED_API_KEY`: Vast.ai API key (required for non-interactive setup if `--vast-api-key` is not passed).
+- `VASTED_BEARER_TOKEN`: Optional stable proxy token. If omitted, one is generated.
+- `VASTED_CLIENT`: Optional persisted client preset (`openclaw`, `opencode`, `custom`).
+- `VASTED_LLAMA_JINJA`: Optional persisted jinja default (`true/false`).
+
+## Validation Commands
+
+Before opening PRs:
+
+```bash
+uv run ruff check .
+uv run mypy app tests bot.py
+uv run pytest -q
+```

vasted-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog, and this project follows Semantic Versioning.
+
+## [Unreleased]
+
+### Added
+
+- Open-source community docs and templates.
+- Release prep docs/workflow for manual TestPyPI/PyPI publishing.
+- Version sync test between `pyproject.toml` and `app.__version__`.
+
+### Changed
+
+- Improved `down` edge-case handling and usage/billing reporting.

vasted-0.1.0/CLAUDE.md

@@ -0,0 +1,30 @@
+# Vasted
+
+Personal GPU launcher for on-demand LLM inference on Vast.ai.
+
+## Quick Start
+```bash
+uv sync
+uv run vasted setup
+uv run vasted serve
+uv run vasted up
+```
+
+## Stack
+- Python 3.12+, uv only
+- rich (TUI/output), pyyaml (config), httpx (proxy/HTTP), click (CLI)
+- vastai SDK for Vast.ai API
+- Optional: python-telegram-bot
+
+## Architecture
+- `app/` — core modules (config, state, models, vast, proxy, usage)
+- `vasted` — CLI entry point (thin wrapper over app/)
+- `bot.py` — optional Telegram adapter
+
+## Key Rules
+1. CLI calls core functions directly — never bot handlers
+2. Proxy is THE stable endpoint; worker URL is internal only
+3. Config (user prefs) and state (active worker) are separate files
+4. Bearer token is fixed by user at setup; worker auth is hidden
+5. llama.cpp with GGUF models only (v1)
+6. Use raw Docker image launch flow (no Vast templates): `ghcr.io/ggml-org/llama.cpp:server-cuda` + onstart script

vasted-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,29 @@
+# Code of Conduct
+
+## Our Standard
+
+This project is committed to a respectful, harassment-free experience for everyone.
+
+Examples of expected behavior:
+
+- Be respectful in feedback and discussion.
+- Assume good intent and ask clarifying questions.
+- Focus on technical issues, not people.
+
+Examples of unacceptable behavior:
+
+- Harassment, insults, or discriminatory language.
+- Personal attacks or sustained hostile behavior.
+- Publishing private information without permission.
+
+## Scope
+
+This Code of Conduct applies in project spaces, including issues, pull requests, and related discussions.
+
+## Enforcement
+
+Project maintainers may remove, edit, or reject comments, commits, code, and other contributions not aligned with this Code of Conduct.
+
+## Reporting
+
+Report behavior issues to project maintainers through private channels when possible.

vasted-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to `vasted`
+
+Thanks for contributing.
+
+## Development Setup
+
+```bash
+uv sync --extra dev
+```
+
+## Before Opening a PR
+
+Run the full local checks:
+
+```bash
+uv run ruff check .
+uv run mypy app tests
+uv run pytest -q
+```
+
+## Pull Request Guidelines
+
+- Keep PRs focused and small when possible.
+- Add or update tests when behavior changes.
+- Update docs (`README.md`, command help text) when UX changes.
+- Use clear commit messages explaining intent.
+
+## Code Style
+
+- Python 3.12+.
+- `ruff` enforces lint/format expectations.
+- Prefer explicit typing on new/modified interfaces.
+- Keep command output user-oriented and actionable.
+
+## Reporting Bugs
+
+Use GitHub Issues with:
+
+- Exact command(s) run
+- Relevant config (redact secrets)
+- Expected vs actual behavior
+- Logs or traceback
+
+## Security Issues
+
+Do not open public issues for sensitive vulnerabilities. See `SECURITY.md`.

vasted-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vasted contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vasted-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: vasted
+Version: 0.1.0
+Summary: Personal GPU launcher for on-demand LLM inference on Vast.ai
+Project-URL: Homepage, https://github.com/deeflect/vasted
+Project-URL: Repository, https://github.com/deeflect/vasted
+Project-URL: Issues, https://github.com/deeflect/vasted/issues
+Author: vasted contributors
+License: MIT License
+        
+        Copyright (c) 2026 vasted contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cli,inference,llama.cpp,llm,proxy,vast.ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1.7
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: keyring>=25.0.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: rich>=13.7.1
+Requires-Dist: starlette>=0.37.2
+Requires-Dist: uvicorn>=0.30.0
+Provides-Extra: dev
+Requires-Dist: httpx[test]; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: telegram
+Requires-Dist: python-telegram-bot>=21.0; extra == 'telegram'
+Description-Content-Type: text/markdown
+
+# vasted
+
+[![CI](https://github.com/deeflect/vasted/actions/workflows/ci.yml/badge.svg)](https://github.com/deeflect/vasted/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+`vasted` is a CLI that launches on-demand Vast.ai GPU workers for `llama.cpp` GGUF inference and exposes a stable OpenAI-compatible `/v1` endpoint.
+
+Built by [deeflect.com](https://deeflect.com) · Follow on X: [x.com/deeflectcom](https://x.com/deeflectcom)
+
+## Demo
+
+![vasted demo](docs/assets/demo.gif)
+
+## Why `vasted`
+
+- Stable client endpoint while worker URLs rotate.
+- Setup wizard for local machine and VPS deployments.
+- Non-interactive automation mode for agents/CI.
+- OpenAI-compatible proxy for tools that expect `/v1` APIs.
+- Session usage and cost tracking.
+- Optional Telegram bot control commands.
+
+## Requirements
+
+- Python `3.12+`
+- [`uv`](https://docs.astral.sh/uv/)
+- Vast.ai account + API key
+- Optional: Telegram bot token (`telegram` extra)
+
+## Install
+
+### Use from source (recommended while iterating)
+
+```bash
+git clone https://github.com/deeflect/vasted.git
+cd vasted
+uv sync --extra dev
+```
+
+Run CLI commands from the repo:
+
+```bash
+uv run vasted --help
+```
+
+### Install as a tool
+
+```bash
+uv tool install "git+https://github.com/deeflect/vasted.git"
+```
+
+Upgrade later:
+
+```bash
+uv tool upgrade vasted
+```
+
+## Quick Start
+
+```bash
+uv run vasted setup
+uv run vasted up
+uv run vasted status --verbose
+```
+
+Client connection values after setup:
+
+- Base URL: `http://<host>:<port>/v1`
+- Auth header: `Authorization: Bearer <token>`
+
+When `proxy_host` is `0.0.0.0`, use your real machine/VPS IP or domain in clients.
+
+## Automation / Unattended Mode
+
+Use non-interactive commands to avoid prompts:
+
+```bash
+uv run vasted setup --non-interactive \
+  --vast-api-key "$VASTED_API_KEY" \
+  --bearer-token "$VASTED_BEARER_TOKEN" \
+  --client openclaw \
+  --deployment-mode local_pc \
+  --model qwen3-coder-30b \
+  --quality balanced \
+  --gpu-mode auto
+
+uv run vasted up --non-interactive --yes --jinja --model qwen3-coder-30b --quality balanced --gpu-mode auto --no-serve
+uv run vasted status --verbose
+uv run vasted usage
+uv run vasted down --force
+```
+
+Environment variables accepted by `setup --non-interactive`:
+
+- `VASTED_API_KEY`
+- `VASTED_BEARER_TOKEN`
+- `VASTED_CLIENT` (`openclaw`, `opencode`, `custom`)
+- `VASTED_LLAMA_JINJA` (`true`/`false`)
+- `VASTED_MODEL`, `VASTED_QUALITY`, `VASTED_GPU_MODE`, `VASTED_GPU_PRESET`
+- `VASTED_DEPLOYMENT_MODE`, `VASTED_PROXY_HOST`, `VASTED_PROXY_PORT`, `VASTED_PUBLIC_HOST`
+
+## Client Profiles and Jinja Behavior
+
+`setup` supports client presets that define default `llama.cpp --jinja` behavior:
+
+- `--client openclaw`: jinja on by default
+- `--client opencode`: jinja off by default
+- `--client custom`: keep/manual behavior
+
+Per launch override is still available:
+
+```bash
+uv run vasted up --jinja
+uv run vasted up --no-jinja
+```
+
+## Command Reference
+
+```bash
+vasted setup [--non-interactive] [--manual] [--client openclaw|opencode|custom]
+vasted up [--model ...] [--quality ...] [--gpu-mode auto|manual] [--gpu-preset ...] [--profile ...] [--max-price ...] [--jinja|--no-jinja] [--yes] [--non-interactive] [--serve|--no-serve]
+vasted down [--force]
+vasted status [--verbose]
+vasted logs [--instance-id N] [--tail N]
+vasted usage
+vasted token show [--full]
+vasted token rotate
+vasted rotate-token
+vasted config show
+vasted profile list|add|use|remove
+vasted completions <bash|zsh|fish>
+```
+
+## Telegram Bot (Optional)
+
+Install telegram extra and run:
+
+```bash
+uv sync --extra telegram
+uv run python bot.py
+```
+
+## Development
+
+```bash
+uv run ruff check .
+uv run mypy app tests bot.py
+uv run pytest -q
+```
+
+## Project Layout
+
+- `app/commands/*`: CLI command handlers
+- `app/service.py`: worker lifecycle + launch policy
+- `app/proxy.py`: OpenAI-compatible reverse proxy
+- `app/vast.py`: Vast API integration + startup script generation
+- `app/usage.py`: token/time/cost accounting
+- `app/user_config.py`: persistent config + keyring integration
+- `app/state.py`: runtime state persistence
+- `bot.py`: optional Telegram control plane
+
+## Security
+
+- Keep Vast API keys and bearer tokens private.
+- Prefer localhost binds unless remote access is required.
+- See [SECURITY.md](./SECURITY.md) for disclosure policy.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) and run the validation commands before opening a PR.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).