{"id":30496239,"url":"https://github.com/codenlighten/ubuntu-ai","last_synced_at":"2025-08-25T01:24:17.329Z","repository":{"id":308969718,"uuid":"1034106803","full_name":"codenlighten/ubuntu-ai","owner":"codenlighten","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-09T01:08:01.000Z","size":40,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-09T01:13:40.189Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codenlighten.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-08-07T21:19:26.000Z","updated_at":"2025-08-09T01:08:05.000Z","dependencies_parsed_at":"2025-08-09T01:13:42.670Z","dependency_job_id":"9ec065d4-e8b5-4cba-96b2-2942b62eaf39","html_url":"https://github.com/codenlighten/ubuntu-ai","commit_stats":null,"previous_names":["codenlighten/ubuntu-ai"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/codenlighten/ubuntu-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenlighten%2Fubuntu-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenlighten%2Fubuntu-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenlighten%2Fubuntu-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenlighten%2Fubuntu-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codenlighten","download_url":"https://codeload.github.com/codenlighten/ubuntu-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenlighten%2Fubuntu-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271990685,"owners_count":24854703,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-24T02:00:11.135Z","response_time":111,"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":[],"created_at":"2025-08-25T01:24:14.690Z","updated_at":"2025-08-25T01:24:17.323Z","avatar_url":"https://github.com/codenlighten.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI System Administrator\n\nThis project is an AI-powered agent designed to manage and administer an Ubuntu system. It uses OpenAI's GPT models to reason about a high-level goal, and then executes specific, structured actions to achieve it. The agent is designed for continuous operation, with persistent history and a focus on security.\n\n## Core Features\n\n- **Autonomous Operation:** The agent runs in a continuous loop to achieve its goal, effectively operating in a fully autonomous \"auto mode.\"\n- **Owner Control:** The owner can gracefully stop the agent at any time by sending a simple signal, without needing to kill the process.\n- **Self-Improvement via Scripting:** The agent can write and execute its own shell scripts to perform complex tasks or create new tools for itself, operating within a secure `scripts/` directory.\n- **Inter-Agent Communication:** The agent can spawn sub-agents to delegate complex tasks, allowing for parallel work and hierarchical problem-solving. Each sub-agent operates with its own independent history.\n- **Goal-Oriented Operation:** Provide a high-level goal (e.g., \"Harden system security and install monitoring tools\"), and the agent will devise and execute a plan.\n- **Persistent History:** The agent saves its action history in `history.json`, allowing it to learn from past actions and resume its work after a restart.\n- **Secure Execution:** Actions are executed by a designated, non-root user (`AGENT_USER`) where possible, minimizing security risks.\n- **Structured Actions:** The agent operates on a strict, predefined schema of actions, preventing arbitrary command execution and ensuring predictable behavior.\n- **Extensible:** New capabilities can be added by defining them in the `systemActionSchema.js` and implementing them in `controlPlane.js`.\n\n## Deployment\n\nDeploying the agent to a fresh Ubuntu server is automated with the `deploy.sh` script.\n\n1.  **Run the Deployment Script:**\n\n    On your new server, download and run the deployment script:\n\n    ```bash\n    wget https://raw.githubusercontent.com/codenlighten/ubuntu-ai/main/deploy.sh\n    chmod +x deploy.sh\n    sudo ./deploy.sh\n    ```\n\n    This script will:\n    - Install all necessary dependencies (Node.js, npm, git).\n    - Clone the repository into `/opt/ubuntu-ai-agent`.\n    - Install Node.js packages.\n    - Create a secure, non-root `agent_user`.\n    - Configure the necessary `sudo` permissions for the agent.\n    - Create a `.env` file from the example.\n\n2.  **Configure the Agent:**\n\n    You must add your OpenAI API key and set the agent's high-level goal in the `.env` file:\n\n    ```bash\n    sudo nano /opt/ubuntu-ai-agent/.env\n    ```\n\n3.  **Install and Start the Service:**\n\n    To run the agent persistently in the background, install and enable the provided `systemd` service:\n\n    ```bash\n    # Copy the service file to the systemd directory\n    sudo cp /opt/ubuntu-ai-agent/service/ubuntu-agent.service /etc/systemd/system/\n\n    # Reload the systemd daemon, enable the service to start on boot, and start it now\n    sudo systemctl daemon-reload\n    sudo systemctl enable ubuntu-agent.service\n    sudo systemctl start ubuntu-agent.service\n    ```\n\n4.  **Monitor the Agent:**\n\n    You can check the agent's status and view its logs using `systemctl` and `journalctl`:\n\n    ```bash\n    # Check status\n    sudo systemctl status ubuntu-agent.service\n\n    # View live logs\n    sudo journalctl -u ubuntu-agent.service -f\n    ```\n\n## Local Development\n\n1.  **Clone the repository.**\n2.  **Install dependencies:**\n    ```bash\n    npm install\n    ```\n3.  **Configure Environment:** Copy `.env.example` to `.env` and set the required values:\n    - `OPENAI_API_KEY`: Your API key for the OpenAI service.\n    - `GOAL`: The high-level objective for the agent.\n    - `AGENT_USER`: (Optional) The local system user the agent should run as. Defaults to `root` if not set.\n    - `STOP_SIGNAL_FILE`: (Optional) The name of the file used to signal a shutdown. Defaults to `STOP`.\n\n4.  **Run the Agent:**\n    ```bash\n    npm start\n    ```\n\nFor continuous operation, it is recommended to run the orchestrator as a `systemd` service (see `overview.md` for an example).\n\n## Auto Mode and Owner Control\n\nThe agent is designed to run autonomously in a continuous loop. To stop the agent, you don't need to find and kill the process. Instead, you can create a signal file in the agent's directory. By default, this file is named `STOP`.\n\nTo stop the agent, simply run this command in the project directory:\n```bash\ntouch STOP\n```\nOn its next cycle, the agent will detect this file, shut down gracefully, and remove the file so it's ready for the next run.\n\n## Supported Actions\n\nThe agent can perform the following actions:\n\n- `update_system`: Updates all system packages.\n- `install_package`: Installs a software package using `apt`.\n- `create_user`: Creates a new user on the system.\n- `configure_file`: Writes content to a specified file.\n- `read_file`: Reads the content of a specified file.\n- `get_system_stats`: Retrieves current disk, memory, and load statistics.\n- `browse_web`: Fetches the textual content of a given URL.\n- `create_script`: Creates a new executable script in the `scripts/` directory.\n- `execute_script`: Runs a script from the `scripts/` directory.\n- `spawn_agent`: Deploys a new, independent agent with a specific goal.\n- `enable_service`: Enables and starts a `systemd` service.\n- `open_port`: Opens a port in the UFW firewall.\n- `run_cmd`: Executes a shell command.\n- `finish`: Terminates the orchestration loop upon completing the goal.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodenlighten%2Fubuntu-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodenlighten%2Fubuntu-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodenlighten%2Fubuntu-ai/lists"}