What this does

Setting up a Manus AI agent provides a general-purpose autonomous agent capable of browsing the web, executing code, and interacting with APIs. Manus agents operate in a sandboxed environment with tool-use capabilities including terminal access, file system operations, and HTTP requests. The setup process installs the Manus package, configures the model backend, and initializes an agent session ready for task delegation.

Steps

First, create a virtual environment and install the Manus package: python -m venv manus-env && source manus-env/bin/activate && pip install manus-agent. Next, set the API key as an environment variable: export MANUS_API_KEY="your-key-here". Configure the agent runtime by creating a config.yaml file specifying the model backend—use "ollama" for local inference or "manus-cloud" for the hosted service. Define the workspace directory where the agent stores temporary files: mkdir -p ~/manus-workspace. Initialize the agent with manus init --workspace ~/manus-workspace. Finally, test the connection with manus run "List the files in the current directory" to verify the agent responds correctly.

Record the local run evidence. Save the exact command, runtime or package version, model name if applicable, and observed output so the result can be reproduced later.
Confirm the local starting state. Print the active binary, package version, model name, or configuration path before changing the workflow.
Run the smallest complete path. Execute the minimum command or script that proves the guide works end to end on the local machine.
Compare against expected output. Check the final line, status code, generated artifact, or model response against the verification section before expanding the setup.
Record the local run evidence. Save the exact command, runtime or package version, model name if applicable, and observed output so the result can be reproduced later.

Verification

Run manus status to confirm the agent service is active and the model backend is reachable. Execute manus run "echo hello world" and verify the output contains "hello world" without errors. Check the workspace directory for a session.log file showing successful initialization. Run manus run "What is 2+2?" and confirm the response includes "4". Test file creation with manus run "Create a file named test.txt with content 'success'" then verify ~/manus-workspace/test.txt exists with the correct content.

Common failures

API key not recognized: Verify the key in the Manus dashboard and ensure it is exported correctly with echo $MANUS_API_KEY. Model backend timeout: Check that Ollama is running with ollama ps and the model is pulled with ollama pull <model-name>. Workspace permission denied: Ensure the workspace directory has write permissions using chmod 755 ~/manus-workspace. Python version mismatch: Confirm Python 3.10+ is active with python --version and recreate the virtual environment if needed. Agent hangs on web requests: Set a timeout in config.yaml under network.timeout_seconds with a value like 30.

Version mismatch - The installed package or runtime differs from the command shown; check the version first and rerun the smallest verification command.
Local environment drift - Another service, virtual environment, model, or path is being used; print the active binary path and configuration before changing the guide steps.

Related guides

build-langgraph-agent-scratch
setup-agent-tool-use-function-calling
implement-web-search-ai-agents