{"id":50404726,"url":"https://github.com/megamen32/gptadmin_opensource","last_synced_at":"2026-05-31T01:03:08.322Z","repository":{"id":357145457,"uuid":"1235588595","full_name":"megamen32/gptadmin_opensource","owner":"megamen32","description":"plugin for Chatgpt to control your computers. Like openclaw/claude code/codex but works totaly free without any subscriptions","archived":false,"fork":false,"pushed_at":"2026-05-11T13:35:07.000Z","size":58,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-11T15:31:14.951Z","etag":null,"topics":["chatgpt-app","chatgpt-plugin","chatgpt-plugins","serveradministration"],"latest_commit_sha":null,"homepage":"https://became.bezrabotnyi.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/megamen32.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-11T13:18:56.000Z","updated_at":"2026-05-11T13:35:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/megamen32/gptadmin_opensource","commit_stats":null,"previous_names":["megamen32/gptadmin_opensource"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/megamen32/gptadmin_opensource","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megamen32%2Fgptadmin_opensource","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megamen32%2Fgptadmin_opensource/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megamen32%2Fgptadmin_opensource/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megamen32%2Fgptadmin_opensource/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/megamen32","download_url":"https://codeload.github.com/megamen32/gptadmin_opensource/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megamen32%2Fgptadmin_opensource/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33715214,"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-05-30T02:00:06.278Z","response_time":92,"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":["chatgpt-app","chatgpt-plugin","chatgpt-plugins","serveradministration"],"created_at":"2026-05-31T01:03:07.466Z","updated_at":"2026-05-31T01:03:08.303Z","avatar_url":"https://github.com/megamen32.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GPTAdmin\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eConnect ChatGPT to your own servers.\u003c/strong\u003e\u003cbr\u003e\n  A small self-hosted control plane that lets an AI assistant inspect machines, run commands, read logs, fix configs, restart services, and report what changed.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#why\"\u003eWhy\u003c/a\u003e ·\n  \u003ca href=\"#how-it-works\"\u003eHow it works\u003c/a\u003e ·\n  \u003ca href=\"#quick-start\"\u003eQuick start\u003c/a\u003e ·\n  \u003ca href=\"#chatgpt-action-setup\"\u003eChatGPT Action setup\u003c/a\u003e ·\n  \u003ca href=\"#security-model\"\u003eSecurity\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What is GPTAdmin?\n\nGPTAdmin is an open-source server-control plugin for ChatGPT-style assistants.\n\nIt gives your assistant a narrow HTTP API for real administration tasks: list your machines, inspect system state, run shell commands, read service logs, edit files through controlled operations, and return a useful report instead of just telling you what to copy into SSH.\n\nThe public landing page describes the idea as an assistant “that does, not only advises”: install software, validate configs, restart services, check logs, and automate routine maintenance across your own machines. See the live demo/docs at \u003chttps://became.bezrabotnyi.com\u003e.\n\n\u003e GPTAdmin is best understood as **SSH-like power exposed through a self-hosted API**. Treat it with the same seriousness as root SSH access.\n\n---\n\n## Why\n\nModern assistants are good at DevOps reasoning, but most of the time they still stop at instructions:\n\n```text\nRun this command.\nPaste the output.\nNow edit this file.\nRestart that service.\nSend me the logs.\n```\n\nGPTAdmin closes that loop. You can ask:\n\n```text\nCheck why nginx is down on server-100 and fix it if the config error is obvious.\n```\n\nThe assistant can then:\n\n1. list registered servers;\n2. read system/service state;\n3. inspect `journalctl` or nginx logs;\n4. propose or apply a small fix;\n5. restart the service;\n6. verify the result;\n7. summarize exactly what happened.\n\nThis repository is intentionally small and hackable. It is not trying to be a full enterprise dashboard. It is a practical building block for homelabs, personal servers, small teams, internal bots, and experiments with AI-assisted operations.\n\n---\n\n## Use cases\n\nGPTAdmin is useful when you want an assistant to help with routine server work:\n\n| Area | Examples |\n| --- | --- |\n| Linux administration | systemd status/restart, package installation, firewall checks, sshd/fail2ban diagnostics |\n| Logs and debugging | `journalctl`, nginx, PostgreSQL, app logs, crash loops, failed units |\n| Web infrastructure | nginx config validation, Certbot checks, Docker Compose health, reverse proxy debugging |\n| VPN and networking | WireGuard/OpenVPN setup, port checks, routing/firewall inspection |\n| Databases | PostgreSQL/Redis diagnostics, backups, slow queries, vacuum/maintenance checks |\n| Game and hobby servers | Minecraft server setup, backups, service restart, resource checks |\n| Fleet convenience | one ChatGPT Action that can work with multiple registered machines |\n\n---\n\n## How it works\n\nGPTAdmin has two main services:\n\n```text\nChatGPT / assistant / script\n        |\n        | Bearer CTL_TOKEN\n        v\n+-------------------+\n| GPTAdmin hub_proxy |\n+-------------------+\n        |\n        | Bearer ROOTD_TOKEN\n        v\n+-------------------+\n| rootd agent        |\n+-------------------+\n        |\n        v\nlocal shell / SSH backend / OS tools\n```\n\n### Components\n\n- **`hub_proxy`** — the central HTTP API. It receives assistant requests, knows which agents are alive, and proxies calls to the selected server.\n- **`rootd`** — the agent running on a target machine. It performs local operations and returns structured results.\n- **`rootd_pure`** — a dependency-light agent variant using only the Python standard library, useful for minimal Unix-like systems.\n- **OpenAPI schema** — the contract imported into ChatGPT Actions or other tool-calling systems.\n- **CLI installer** — an interactive setup flow for installing services and managing tokens.\n\nAgents register themselves through heartbeats. The hub keeps live registrations in memory. Assistant requests usually include `?server=\u003cname\u003e`, and the hub forwards the operation to the matching agent.\n\n---\n\n## Repository layout\n\n```text\ncli/                         interactive installer and service manager\ndeploy/                      Linux/Windows install helpers\nservices/main_package/\n  hub_proxy.py               central hub / reverse proxy\n  client/rootd.py            FastAPI server agent\n  client/rootd_pure.py       stdlib-only agent for minimal systems\n  client/rootd_linux.py      Linux command backend\n  client/rootd_win.py        Windows command backend\n  client/rootd_ssh.py        SSH command backend\ndocs/                        architecture, ChatGPT setup, API, security, operations\npublic/                      OpenAPI schema and plugin/action metadata examples\ntests/                       smoke/integration tests\ntools/                       build and audit helpers\nexamples/                    environment examples\n```\n\n---\n\n## Quick start\n\n\n### One-command installer\n\nFor a real machine, use the interactive installer:\n\n```bash\ncurl -sSL https://became.bezrabotnyi.com/install.sh | sudo bash\n```\n\nThe installer can set up:\n\n- hub + local rootd on the main machine;\n- rootd-only agents on additional machines;\n- tokens used by the hub and agents;\n- systemd services;\n- an optional public tunnel when you do not have a static IP or domain.\n\nAfter installation it prints the hub URL and control token that you can use in ChatGPT Actions.\n\nFor local development from this repository, you can also run:\n\n```bash\nsudo python cli/gptadmin.py setup\nsudo gptadmin status\nsudo gptadmin logs hub\nsudo gptadmin tokens\n```\n\n\n### 1. Install dependencies\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n```\n\n### 2. Start the hub and one local agent\n\n```bash\nexport CTL_TOKEN=\"dev-control-token-change-me\"\nexport ROOTD_TOKEN=\"dev-agent-token-change-me\"\nexport HUB_URL=\"http://127.0.0.1:48653\"\nexport ROOTD_URL=\"http://127.0.0.1:48652\"\n\nuvicorn services.main_package.hub_proxy:app --host 127.0.0.1 --port 48653 \u0026\nuvicorn services.main_package.client.rootd:app --host 127.0.0.1 --port 48652 \u0026\n```\n\n### 3. ChatGPT Action setup\n\nGPTAdmin works well as a custom ChatGPT Action because the hub exposes an OpenAPI schema.\n\n1. Open the GPT editor.\n2. Create a new Action.\n3. Import the OpenAPI schema from your hub or from `public/openapi.json`.\n4. Replace the schema `servers.url` with your own hub URL.\n5. Set authentication to API key / Bearer token.\n6. Use your `CTL_TOKEN` as the token.\n7. Ask the assistant to call `listServers` first, then use a specific server name for operations.\n\nRecommended assistant instruction:\n\n```text\nYou are connected to GPTAdmin, a self-hosted server administration API.\nFirst call listServers when the target server is unclear.\nPrefer read-only diagnostics before modifying the system.\nBefore destructive commands, explain the exact command and ask for confirmation.\nAfter every change, verify the result and summarize what changed.\n```\n\nMore details: [`docs/CHATGPT_ACTION.md`](docs/CHATGPT_ACTION.md).\n\n---\n\n\n## API examples\n\nList registered servers:\n\n```bash\ncurl -sS \"$HUB_URL/servers\" \\\n  -H \"Authorization: Bearer $CTL_TOKEN\"\n```\n\nRun a command:\n\n```bash\ncurl -sS \"$HUB_URL/srv/exec?server=server-100\" \\\n  -H \"Authorization: Bearer $CTL_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"cmd\":\"systemctl status nginx --no-pager\", \"timeout\": 20}'\n```\n\nGet system info:\n\n```bash\ncurl -sS \"$HUB_URL/srv/system/info?server=server-100\" \\\n  -H \"Authorization: Bearer $CTL_TOKEN\"\n```\n\nSee [`docs/API.md`](docs/API.md) and [`public/openapi.json`](public/openapi.json).\n\n---\n\n## Security model\n\nGPTAdmin can execute commands on machines where the agent runs. That is powerful and dangerous by design.\n\nMinimum safe setup:\n\n- use long random tokens;\n- expose only the hub, not every agent;\n- put the hub behind HTTPS;\n- bind agents to private networks where possible;\n- restrict allowed commands for untrusted users;\n- log every operation;\n- rotate tokens if configs, logs, terminal output, or backups leak;\n- do not connect it to machines you do not own or administer.\n\nRecommended operating pattern:\n\n1. diagnostics first;\n2. exact proposed fix second;\n3. explicit confirmation for destructive operations;\n4. verification after each change;\n5. final report with commands and files touched.\n\nRead [`SECURITY.md`](SECURITY.md) before exposing GPTAdmin outside localhost.\n\n---\n\n## Configuration\n\nCopy the example environment file:\n\n```bash\ncp examples/gptadmin.env.example .env\n```\n\nImportant variables:\n\n| Variable | Used by | Description |\n| --- | --- | --- |\n| `CTL_TOKEN` | hub | Control-plane bearer token. Required. |\n| `ROOTD_TOKEN` | agent | Agent bearer token. Required. |\n| `HUB_URL` | agent | Hub URL used for heartbeats. |\n| `ROOTD_URL` | agent | Public URL of the agent. |\n| `ROOTD_PORT` | agent | Agent HTTP port. Default: `48652`. |\n| `HUB_PORT` | hub | Hub HTTP port. Default: `48653`. |\n| `SSH_HOST` | agent | Enables SSH backend instead of local execution. |\n| `SSH_PORT` | agent | SSH port for remote backend. |\n| `SSH_USER` | agent | SSH user for remote backend. |\n| `SSH_PASSWORD` | agent | SSH password, if password auth is used. |\n| `SSH_KEY` | agent | Path to SSH private key. |\n\n---\n\n## SSH backend\n\nIf `rootd` should execute commands on another machine instead of the local host, set `SSH_HOST` and optionally `SSH_PORT`, `SSH_USER`, `SSH_PASSWORD`, or `SSH_KEY` before starting the service.\n\n```bash\nexport SSH_HOST=\"192.168.1.50\"\nexport SSH_USER=\"root\"\nexport SSH_KEY=\"/root/.ssh/id_ed25519\"\nexport ROOTD_TOKEN=\"agent-token\"\n\npython services/rootd.py\n```\n\nThis is useful when the agent is deployed as a gateway into a private network.\n\n---\n\n## Tests\n\n```bash\npytest -q\n```\n\nThe tests start a hub and an agent with local development tokens and verify heartbeat, queue, and command execution flows.\n\n---\n\n## Project status\n\nGPTAdmin is an early, practical open-source project extracted from real server-automation work.\n\nStable enough to experiment with:\n\n- local hub/agent execution;\n- multi-server registration;\n- command execution through hub;\n- OpenAPI import into ChatGPT Actions;\n- basic tests and installer scripts.\n\nStill worth improving:\n\n- persistent server registry;\n- stricter command policy engine;\n- richer audit log;\n- web dashboard;\n- packaged releases;\n- better Windows support;\n- approval workflow for dangerous actions.\n\nContributions are welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n---\n\n## Similar idea, different shape\n\nGPTAdmin is not a replacement for Ansible, Kubernetes, SSH, or observability platforms. It sits in a different layer: a thin action bridge between an AI assistant and machines you control.\n\nUse mature tools for infrastructure state. Use GPTAdmin when you want a conversational operator that can inspect, execute, verify, and summarize.\n\n---\n\n## License\n\n`Creative Commons Attribution-NonCommercial 4.0 International`\n\nThis software is free for personal use. You are allowed to modify and distribute it, but you are strictly prohibited from selling this software or charging for any services directly based on it. See [`LICENSE`](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmegamen32%2Fgptadmin_opensource","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmegamen32%2Fgptadmin_opensource","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmegamen32%2Fgptadmin_opensource/lists"}